Enforce Strict RPC Parameter Boundaries and Reactive Async Primitives in SolidStart 1.0

--- description: Enforce Strict RPC Parameter Boundaries and Reactive Async Primitives in SolidStart 1.0 - SolidStart 1.0 server functions compiled via Nitro/Vinxi extract RPC bodies into isolated server endpoints that have no access to client-side reactive graphs. Reactive primitives (signals, stores) must never be read inside 'use server' or server$ closures; instead, read signals inside tracking scopes (createAsync or createResource) and pass plain serializable primitives as arguments to server functions cached with the cache() wrapper. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-function-reactive-boundaries" --- # Enforce Strict RPC Parameter Boundaries and Reactive Async Primitives in SolidStart 1.0 > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Accessing Client Signals Inside Server Closures and Bypassing createAsync Hydration Caches ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 server functions and reactive async boundaries. You must strictly prevent client-state leakage, hydration mismatches, and broken reactive tracking across the client-server boundary. Key architectural principles to enforce: 1. Server closures ('use server' / server$) run exclusively on the Node/Nitro server environment during RPC execution. Client reactive signals (createSignal, createStore) cannot be closed over or accessed inside server functions. 2. Server RPC calls must be wrapped inside `cache()` for deterministic deduplication during SSR and client navigation, and consumed reactively using `createAsync()`. 3. All arguments passed to server functions must be JSON/Seroval-serializable primitives, plain objects, or FormData. Never pass Functions, DOM elements, or Signal accessors. 4. Avoid unmemoized server mutations or executing side-effecting server RPCs directly in component render bodies without using `action()`. ## Strict Guidelines - Engineers MUST ALWAYS declare server RPCs at module scope using 'use server' directive or server$ wrappers, accepting only serializable parameters. - Engineers MUST ALWAYS wrap server query functions in cache() with an explicit unique key when used for data fetching to prevent waterfall requests and hydration desynchronization. - Engineers MUST ALWAYS evaluate client signals in the client tracking context (e.g., inside createAsync(() => fetchFn(mySignal()))) and pass the resolved value to the server function. - Engineers MUST NOT attempt to access client-side lexical scope variables or reactive signal accessors directly inside a server function body. - Components NEVER execute raw server functions in top-level render cycles without wrapping them in createAsync(), createResource(), or SolidStart action(). - Code MUST use action() with useSubmission() or useAction() for state-mutating server RPCs to guarantee automatic route invalidation and optimistic UI coherence. ## Bad vs Good Implementations ### Direct Signal Capture vs. createAsync Signal Passing with cache() #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing `query()` directly inside `server$` fails because the RPC function executes in Nitro server isolation where client reactive graphs do not exist. Furthermore, invoking a server function directly in component scope without `createAsync` triggers uncached network calls on every re-evaluation and breaks SSR hydration streaming. ```typescript import { createSignal } from "solid-js"; import { server$ } from "@solidjs/start/server"; import { db } from "~/lib/db"; export default function BadSearch() { const [query, setQuery] = createSignal(""); // CRITICAL BUG: Closing over client signal inside server$ boundary. // During Vinxi compilation, this function is stripped to an RPC endpoint. // `query()` is undefined or fails silently on the server runtime. const searchUsers = server$(async () => { return await db.user.findMany({ where: { name: { contains: query() } } }); }); // Hydration mismatch: raw promise call directly in render phase const results = searchUsers(); return ( <div> <input value={query()} onInput={(e) => setQuery(e.currentTarget.value)} /> </div> ); } ``` #### Production Standard (Correct) > **Standard**: The server function is declared at module scope with 'use server', safely receives a serializable `string` parameter, and is wrapped in `cache()` with a unique key. In the component, `createAsync(() => getUsers(query()))` establishes a valid fine-grained reactive dependency on `query()`, refetching and deduplicating RPC executions seamlessly across SSR and client navigations. ```typescript import { createSignal } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { db } from "~/lib/db"; // Module-scoped cached server function receiving plain serializable arguments const getUsers = cache(async (searchQuery: string) => { "use server"; if (!searchQuery.trim()) return []; return await db.user.findMany({ where: { name: { contains: searchQuery } }, select: { id: true, name: true, email: true } }); }, "users.search"); export default function GoodSearch() { const [query, setQuery] = createSignal(""); // Client tracking context passes the unwrapped signal value to the cached RPC const users = createAsync(() => getUsers(query())); return ( <div> <input value={query()} onInput={(e) => setQuery(e.currentTarget.value)} placeholder="Search users..." /> <ul> {users()?.map((u) => ( <li key={u.id}>{u.name} ({u.email})</li> ))} </ul> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Enforce Strict RPC Parameter Boundaries and Reactive Async Primitives in SolidStart 1.0

Enforce Strict RPC Parameter Boundaries and Reactive Async Primitives in SolidStart 1.0 defines an industrial-grade behavioral standard for frontend engineering. SolidStart 1.0 server functions compiled via Nitro/Vinxi extract RPC bodies into isolated server endpoints that have no access to client-side reactive graphs. Reactive primitives (signals, stores) must never be read inside 'use server' or server$ closures; instead, read signals inside tracking scopes (createAsync or createResource) and pass plain serializable primitives as arguments to server functions cached with the cache() wrapper. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Accessing Client Signals Inside Server Closures and Bypassing createAsync Hydration Caches Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Accessing Client Signals Inside Server Closures and Bypassing createAsync Hydration Caches	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS declare server RPCs at module scope using 'use server' directive or server$ wrappers, accepting only serializable parameters.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.