SolidStart 1.0 Server Functions and Async Boundary Invariants

--- description: SolidStart 1.0 Server Functions and Async Boundary Invariants - Enforces strict isolation between client reactive tracking scopes and SolidStart server$ RPC execution contexts. Guarantees that server functions receive explicit, JSON-serializable parameters through createAsync or query primitives rather than capturing client signal accessors in server closures, ensuring deterministic SSR streaming and hydration. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-rpc-reactive-boundary" --- # SolidStart 1.0 Server Functions and Async Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing Over Client Reactive Signals in server$ Handlers or Orchestrating RPCs via Untracked createEffect Lifecycles ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions and Async Boundaries. Mandate that server$ RPCs remain pure serialized boundary endpoints, preventing client signal leaks, hydration mismatches, and cascading network waterfalls. ## Strict Guidelines - Engineers MUST ALWAYS isolate server$ definitions from client reactive scopes by declaring them as pure top-level functions or ensuring all arguments are explicitly passed as serializable values. - Engineers MUST NOT reference client-side signals, stores, or DOM accessors directly inside the lexical closure of a server$ function body. - Code SHOULD pair server$ reads with createAsync and query/cache from @solidjs/router to leverage fine-grained streaming SSR, transition tracking, and deterministic hydration. - Services MUST validate and sanitize all inbound arguments inside the server$ implementation using runtime schema validators (e.g., Valibot, Zod), treating the boundary as an untrusted public HTTP POST/GET endpoint. - Components NEVER execute raw server$ invocations directly inside createEffect or onMount to populate reactive state; async reads must be bound to Suspense and ErrorBoundary hierarchies. ## Bad vs Good Implementations ### Server RPC Invocation with Reactive Tracking and Query Caching #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Referencing the client-side reactive accessor userId() inside the server$ closure fails because server$ extracts the function into an isolated RPC endpoint where client signals do not exist. Fetching via createEffect causes hydration flickers, waterfalls, and misses automatic Suspense integration. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start/server"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); const [userData, setUserData] = createSignal<any>(null); // BAD: Closing over client signal inside server$, triggering RPC inside naked createEffect. // This breaks compiler dead-code elimination, leaks client context into the server bundle, // bypasses SSR streaming, causes hydration waterfalls, and misses Suspense transitions. const fetchUser = server$(async () => { const id = userId(); // Direct closure over client signal: FAILS at compile/runtime return await db.user.findUnique({ where: { id } }); }); createEffect(() => { fetchUser().then(data => setUserData(data)); }); return <div>{userData() ? userData().name : "Loading..."}</div>; } ``` #### Production Standard (Correct) > **Standard**: The RPC receives explicit serializable arguments and is wrapped in query() and createAsync(). Solid tracks userId() in client reactive context, re-executing the cached RPC automatically when it changes, while properly integrating with Suspense for SSR streaming and hydration. ```typescript import { createSignal, Suspense } from "solid-js"; import { query, createAsync } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; // GOOD: Define RPC as an isolated boundary accepting explicit, validated serializable arguments const getUser = query(async (id: string) => { "use server"; if (!id || typeof id !== "string") { throw new Error("Invalid user identifier"); } return await db.user.findUnique({ where: { id } }); }, "getUser"); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // GOOD: Pass a reactive accessor to createAsync. Solid tracks changes to userId() // on the client and calls the cached query without capturing signals across the wire. 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 Functions and Async Boundary Invariants

SolidStart 1.0 Server Functions and Async Boundary Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between client reactive tracking scopes and SolidStart server$ RPC execution contexts. Guarantees that server functions receive explicit, JSON-serializable parameters through createAsync or query primitives rather than capturing client signal accessors in server closures, ensuring deterministic SSR streaming and hydration. 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 Reactive Signals in server$ Handlers or Orchestrating RPCs via Untracked createEffect Lifecycles 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 Reactive Signals in server$ Handlers or Orchestrating RPCs via Untracked createEffect Lifecycles	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 isolate server$ definitions from client reactive scopes by declaring them as pure top-level functions or ensuring all arguments are explicitly passed as serializable values.

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.