SolidStart 1.0 Server Functions and Async Boundary Invariants

--- description: SolidStart 1.0 Server Functions and Async Boundary Invariants - Enforces strict RPC boundary isolation and reactive tracking decoupling when using SolidStart server$ functions. Mandates explicit parameter serialization, prevents lexical capture of client-side reactive signals within server closures, and enforces mandatory Suspense and ErrorBoundary wrapping for all async data-fetching primitives. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-functions-async-boundary-standard" --- # SolidStart 1.0 Server Functions and Async Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Lexical Signal Leakage and Naked Execution in SolidStart Server RPCs ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions & Async Boundaries. You prevent developers from closing over reactive client signals inside server$ closures, prevent untracked server RPC calls inside pure render flows, and mandate explicit serialization boundaries and Suspense wrappers. ## Strict Guidelines - Engineers MUST NEVER close over client signals, stores, or DOM references inside server$ closures; all dynamic input must be explicitly passed as serializable arguments. - Engineers MUST wrap all server function reads in declarative async primitives such as createAsync() paired with cache(), or createResource(), never triggering naked server$ calls directly inside component bodies or tracking computations. - Code MUST wrap every async-bound UI tree in both <Suspense> and <ErrorBoundary> to prevent uncaught RPC rejections from crashing the client runtime or causing hydration mismatches. - Services exposing server$ RPCs MUST validate and sanitize input arguments using runtime schema validators (e.g., Valibot, Zod) before executing database queries or handling internal business logic. - Components NEVER execute mutation-oriented server$ calls during the initial render phase; mutations must be orchestrated through createAction() or user-triggered event handlers. ## Bad vs Good Implementations ### Closing Over Signals vs. Explicit Serializable Arguments with createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Closing over `userId()` inside `server$` breaks Vinxi's client/server bundle isolation, causing serialization panics or accessing undefined scope at runtime. Additionally, calling `getUserData()` nakedly in the render function executes the RPC on every render pass without async coordination or error/suspense boundary management. ```typescript import { createSignal } from "solid-js"; import { server$ } from "@solidjs/start"; import { db } from "~/server/db"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // BAD: Lexically capturing client signal inside server$ closure // This causes Vinxi compilation failure or serialization runtime errors const getUserData = server$(async () => { return await db.user.findUnique({ where: { id: userId() } }); }); // BAD: Naked RPC invocation during render without async boundary const data = getUserData(); return <div>{JSON.stringify(data)}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function explicitly accepts and validates serializable arguments using Zod. Data fetching is properly managed using `cache` and `createAsync`, which reactively tracks `userId()` and coordinates SSR hydration cleanly within `<Suspense>` and `<ErrorBoundary>` boundaries. ```typescript import { createSignal, Suspense } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { server$ } from "@solidjs/start"; import { ErrorBoundary } from "solid-js"; import { z } from "zod"; import { db } from "~/server/db"; const UserIdSchema = z.string().min(1); // GOOD: server$ receives explicit serializable argument and validates input const fetchUser = cache(async (id: string) => { "use server"; const validatedId = UserIdSchema.parse(id); const user = await db.user.findUnique({ where: { id: validatedId } }); if (!user) throw new Error("User not found"); return user; }, "users"); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // GOOD: Bound to reactive system via createAsync with explicit reactive dependency const user = createAsync(() => fetchUser(userId())); return ( <ErrorBoundary fallback={(err) => <p role="alert">Error: {err.message}</p>}> <Suspense fallback={<p>Loading profile...</p>}> <div> <h1>{user()?.name}</h1> <button onClick={() => setUserId("usr_456")}>Switch User</button> </div> </Suspense> </ErrorBoundary> ); } ```

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 RPC boundary isolation and reactive tracking decoupling when using SolidStart server$ functions. Mandates explicit parameter serialization, prevents lexical capture of client-side reactive signals within server closures, and enforces mandatory Suspense and ErrorBoundary wrapping for all async data-fetching primitives. 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: Lexical Signal Leakage and Naked Execution in SolidStart Server RPCs 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	Lexical Signal Leakage and Naked Execution in SolidStart Server RPCs	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 NEVER close over client signals, stores, or DOM references inside server$ closures

Engineers MUST NEVER close over client signals, stores, or DOM references inside server$ closures; all dynamic input must be explicitly passed as serializable arguments.

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.