SolidStart 1.0 Server Function Isolation & Async Boundary Invariants

--- description: SolidStart 1.0 Server Function Isolation & Async Boundary Invariants - Enforces strict serialization and reactivity boundaries across SolidStart server$ RPC calls and client signals. Prohibits closing over client-side reactive state within server$ functions and mandates wrapping server invocations with createAsync to preserve fine-grained Suspense coordination. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-rpc-async-boundary-guardrail" --- # SolidStart 1.0 Server Function Isolation & Async Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing Over Client Signals in server$ RPCs and Uncoordinated Async JSX Evaluation ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions & Async Boundaries. Mandate invariants regarding server$ RPC serialization boundaries, client signal decoupling, input schema validation, and createAsync Suspense coordination. ## Strict Guidelines - Engineers MUST ALWAYS pass client-side signal values as serializable, explicit arguments into server$ functions rather than closing over client signals in the server function body. - Engineers MUST wrap all read-only server RPC invocations using createAsync (or cache) to ensure seamless integration with Solid's fine-grained Suspense boundaries. - Engineers MUST NOT access client-side contexts, signals, or DOM APIs inside the lexical scope of server$ RPC handlers. - Code SHOULD validate all incoming RPC parameters at runtime using schema parsers (e.g., Zod, Valibot) within the server$ entry point before processing business logic. - Components NEVER await raw promises directly within JSX or createEffect without wrapping them in createAsync or an explicit resource primitive, as this causes silent reactivity loss and hydration race conditions. ## Bad vs Good Implementations ### Decouple Client Reactive Signals from server$ and Bind via createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Closing over `userId` inside `server$` attempts to read client-side reactive state across a serialized network boundary, leading to build errors, runtime crashes, or stale captures. Executing a raw promise directly inside JSX bypasses Solid's fine-grained Suspense mechanism. ```typescript import { createSignal, Suspense } from "solid-js"; import { server$ } from "@solidjs/start/server"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // ANTI-PATTERN: Capturing client-side signal inside server$ closure; // invocation is not bound to Solid's async tracking/Suspense primitive. const fetchUser = server$(async () => { const id = userId(); // Fails: signal is evaluated on server or yields stale/undefined reference const db = await import("~/lib/db"); return db.users.findUnique({ where: { id } }); }); return ( <Suspense fallback={<div>Loading...</div>}> {/* ANTI-PATTERN: Direct async function execution breaks fine-grained reactivity */} <div>{fetchUser().then(u => u?.name)}</div> </Suspense> ); } ``` #### Production Standard (Correct) > **Standard**: The server RPC `getUser` takes an explicit string parameter validated by Zod at the RPC perimeter. `createAsync(() => getUser(userId()))` automatically tracks the reactive client signal `userId()`, re-fetches when it updates, and seamlessly registers with `<Suspense>`. ```typescript import { createSignal, Suspense } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; import { z } from "zod"; const UserQuerySchema = z.string().min(1); // GOOD: Define server RPC with explicit serializable parameters and runtime validation const getUser = cache(server$(async (id: string) => { "use server"; const validatedId = UserQuerySchema.parse(id); const db = await import("~/lib/db"); return db.users.findUnique({ where: { id: validatedId } }); }), "getUser"); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // GOOD: Track client signal via accessor function inside createAsync const user = createAsync(() => getUser(userId())); return ( <Suspense fallback={<div>Loading user profile...</div>}> <div>{user()?.name}</div> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Function Isolation & Async Boundary Invariants

SolidStart 1.0 Server Function Isolation & Async Boundary Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict serialization and reactivity boundaries across SolidStart server$ RPC calls and client signals. Prohibits closing over client-side reactive state within server$ functions and mandates wrapping server invocations with createAsync to preserve fine-grained Suspense coordination. 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: Closing Over Client Signals in server$ RPCs and Uncoordinated Async JSX Evaluation 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	Closing Over Client Signals in server$ RPCs and Uncoordinated Async JSX Evaluation	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 pass client-side signal values as serializable, explicit arguments into server$ functions rather than closing over client signals in the server function body.

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.