SolidStart 1.0 Server Function Serialization & Reactive Async Boundary Isolation

--- description: SolidStart 1.0 Server Function Serialization & Reactive Async Boundary Isolation - Enforces strict boundary separation between client-side reactive graphs and Vinxi/Nitro server RPCs (server$, action, query/cache). Guarantees zero leakage of non-serializable signal accessors across the network wire, prevents hydration mismatches via mandatory Suspense boundaries on createAsync, and mandates isolated server-side request context handling. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-rpc-async-boundaries-production-standard" --- # SolidStart 1.0 Server Function Serialization & Reactive Async Boundary Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Capturing Client Reactive Signals in server$ Closures and Omitting Suspense on createAsync Boundaries ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 Server Functions and Async Boundary safety. You must guarantee that client-side reactive signals are never closed over inside `server$` bodies, server calls are pure and strictly serializable, and every asynchronous boundary is guarded by Suspense and ErrorBoundary primitives to maintain isomorphic SSR hydration integrity. ## Strict Guidelines - Engineers MUST ALWAYS pass plain, serialized primitives or JSON-compatible objects into `server$` functions rather than closing over component-scoped signals or reactive accessors. - Engineers MUST NOT access SolidJS client reactivity primitives (`createSignal`, `createMemo`, store proxies) inside the lexical scope of a `server$` body. - Code MUST wrap any data read derived from `createAsync` or `cache` inside a `<Suspense>` boundary to prevent synchronous hydration mismatch errors and DOM thrashing. - Services invoked via `server$` MUST retrieve request metadata explicitly via `getRequestEvent()` inside the server function execution context rather than relying on global client singletons. - Components NEVER render `createAsync` accessors outside of a tracked reactive JSX context or without an enclosing `<ErrorBoundary>`. ## Bad vs Good Implementations ### Lexical Signal Leakage vs. Explicit Serializable Parameterization in server$ #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Closing over `filter()` inside the server function closure fails during compilation or serializes undefined because client signals cannot cross the RPC boundary. Furthermore, accessing `user()?.name` directly without `<Suspense>` triggers hydration mismatch warnings and breaks stream serialization. ```typescript import { createSignal } from "solid-js"; import { createAsync } from "@solidjs/router"; export default function UserProfile(props: { userId: string }) { const [filter, setFilter] = createSignal("active"); // ANTI-PATTERN: Closing over client signal inside server$ closure // This triggers serialization failure or creates stale server closures const getUserData = () => { "use server"; return db.users.findUnique({ where: { id: props.userId, status: filter() } // Error: filter is client signal }); }; const user = createAsync(() => getUserData()); // Missing Suspense boundary leads to hydration mismatch / SSR flicker return <div>{user()?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function receives plain strings as parameters, ensuring clean JSON serialization across the wire. Client reactivity drives the caller function passed into `createAsync`. Suspense and ErrorBoundary components isolate the asynchronous boundary during SSR streaming and hydration. ```typescript import { createSignal, Suspense, ErrorBoundary } from "solid-js"; import { query, createAsync } from "@solidjs/router"; import { getRequestEvent } from "solid-js/web"; // GOOD: Define cached server query accepting explicit, serializable parameters const getUserData = query(async (userId: string, status: string) => { "use server"; const event = getRequestEvent(); if (!event) throw new Error("Request context unavailable"); return db.users.findUnique({ where: { id: userId, status } }); }, "getUserData"); export default function UserProfile(props: { userId: string }) { const [filter, setFilter] = createSignal("active"); // GOOD: Feed signal values into the query via tracking accessor const user = createAsync(() => getUserData(props.userId, filter())); return ( <ErrorBoundary fallback={(err) => <div>Error: {err.message}</div>}> <Suspense fallback={<div>Loading profile...</div>}> <div>{user()?.name}</div> </Suspense> </ErrorBoundary> ); } ```

Architectural Specification & Invariant Rationale

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

SolidStart 1.0 Server Function Serialization & Reactive Async Boundary Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary separation between client-side reactive graphs and Vinxi/Nitro server RPCs (server$, action, query/cache). Guarantees zero leakage of non-serializable signal accessors across the network wire, prevents hydration mismatches via mandatory Suspense boundaries on createAsync, and mandates isolated server-side request context handling. 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: Capturing Client Reactive Signals in server$ Closures and Omitting Suspense on createAsync Boundaries 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	Capturing Client Reactive Signals in server$ Closures and Omitting Suspense on createAsync Boundaries	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 plain, serialized primitives or JSON-compatible objects into `server$` functions rather than closing over component-scoped signals or reactive accessors.

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.