SolidStart 1.0 server$ RPC Serialization & Async Boundary Invariants

--- description: SolidStart 1.0 server$ RPC Serialization & Async Boundary Invariants - Mandates strict isolation and explicit serialization boundaries for SolidStart 1.0 server$ RPCs and fine-grained client signals. Prevents closure leakage across the client/server network boundary, serialization failures, and broken SSR streaming by enforcing createAsync wrappers within Suspense boundaries. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-function-async-boundary-guardrails" --- # SolidStart 1.0 server$ RPC Serialization & Async Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing over reactive client signals inside server$ RPC closures and executing untracked async operations outside createAsync ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions & Async Boundaries. Mandate strict parameterization of server$ endpoints, zero closure leakage of client-side reactive state into server code, and consistent wrapping of server data fetching in createAsync and Suspense boundaries. ## Strict Guidelines - Engineers MUST ALWAYS pass primitive or JSON-serializable values as explicit arguments to server$ functions rather than closing over component-scoped signals or reactive state. - Engineers MUST wrap all read-only server$ data queries in createAsync() from @solidjs/router to retain fine-grained reactivity, transition awareness, and streaming SSR support. - Engineers MUST NOT execute mutating RPCs inside createAsync accessors; mutations MUST be handled via action(server$(...)) or isolated server$ calls bound to explicit event handlers. - Code SHOULD validate all inbound payloads inside server$ entry points using strict schemas (e.g., Valibot, Zod) before performing business logic or database operations. - Components NEVER read raw pending Promise instances directly in JSX; asynchronous read boundaries MUST be declared with createAsync and encapsulated by <Suspense fallback={<Loader />}>. ## Bad vs Good Implementations ### server$ Signal Closure Leakage vs. Explicit Parameterization with createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Attempting to read client-side reactive signals (userId()) inside the server$ body violates the execution boundary because server$ is compiled into an isolated HTTP endpoint running in Nitro/Node. Calling server$ directly without createAsync breaks Solid's reactive tracking and Suspense coordination. ```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: Closing over client signal inside server$ closure // Causes build-time AST extraction failure, runtime serialization errors, or stale captured state const fetchUserData = server$(async () => { const id = userId(); // Leaked client closure across network boundary! const user = await db.user.findUnique({ where: { id } }); return user; }); // ANTI-PATTERN: Calling server$ directly as a raw promise without createAsync inside render const rawDataPromise = fetchUserData(); return ( <Suspense fallback={<div>Loading...</div>}> {/* Fails fine-grained reactivity and SSR streaming contracts */} <div>User: {JSON.stringify(rawDataPromise)}</div> </Suspense> ); } ``` #### Production Standard (Correct) > **Standard**: The server$ function is purely parameterized, accepting an explicit argument verified at the network boundary. On the client, createAsync subscribes to the reactive userId() signal, invoking the RPC whenever it updates and correctly signaling the surrounding Suspense boundary. ```typescript import { createSignal, Suspense, Show } from "solid-js"; import { createAsync } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; // INVARIANT: server$ declared with explicit serializable parameters and boundary isolation const fetchUserData = server$(async (id: string) => { "use server"; if (!id || typeof id !== "string") { throw new Error("Invalid payload: id must be a string"); } const user = await db.user.findUnique({ where: { id } }); if (!user) throw new Error("User not found"); return user; }); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // INVARIANT: createAsync tracks signal dependencies and pipes resolved state through Suspense const user = createAsync(() => fetchUserData(userId())); return ( <Suspense fallback={<div>Loading user profile...</div>}> <Show when={user()} fallback={<div>No user data</div>}> {(data) => <div>User: {data().name}</div>} </Show> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 server$ RPC Serialization & Async Boundary Invariants

SolidStart 1.0 server$ RPC Serialization & Async Boundary Invariants defines an industrial-grade behavioral standard for frontend engineering. Mandates strict isolation and explicit serialization boundaries for SolidStart 1.0 server$ RPCs and fine-grained client signals. Prevents closure leakage across the client/server network boundary, serialization failures, and broken SSR streaming by enforcing createAsync wrappers within Suspense boundaries. 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 reactive client signals inside server$ RPC closures and executing untracked async operations outside createAsync 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 reactive client signals inside server$ RPC closures and executing untracked async operations outside createAsync	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 primitive or JSON-serializable values as explicit arguments to server$ functions rather than closing over component-scoped signals or reactive state.

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.