SolidStart 1.0 Server Functions & Async Boundaries Production Standard

SolidStart 1.0 relies on the Vinxi bundler to split `server$` closures into independent HTTP POST RPC endpoints. Direct lexical closure over client signals within `server$` scopes or failure to demarcate async boundaries with `<Suspense>` causes silent serialization failures, client-bundle secret leaks, and SSR hydration mismatches. Enforcing strict parameter passing, runtime input validation, and Solid async primitives maintains security and fine-grained reactivity across network boundaries.

--- description: SolidStart 1.0 Server Functions & Async Boundaries Production Standard - SolidStart 1.0 relies on the Vinxi bundler to split `server$` closures into independent HTTP POST RPC endpoints. Direct lexical closure over client signals within `server$` scopes or failure to demarcate async boundaries with `<Suspense>` causes silent serialization failures, client-bundle secret leaks, and SSR hydration mismatches. Enforcing strict parameter passing, runtime input validation, and Solid async primitives maintains security and fine-grained reactivity across network boundaries. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-1-0-server-functions-async-boundaries-production-standard" --- # SolidStart 1.0 Server Functions & Async Boundaries Production Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing over reactive client signals inside server$ RPCs or calling unvalidated server functions directly in reactive effects. ## System Constraints You are an expert SolidStart 1.0 systems engineer. Enforce strict isolation between client execution contexts and server$ RPC handlers. Never capture client-side reactive state inside server closures; always validate server payloads at the network boundary and isolate server-only modules. ## Strict Guidelines - Developers MUST NOT close over reactive client signals, component props, or client-side DOM state inside `server$` closures; all state MUST be passed explicitly as serializable arguments. - All parameters consumed inside a `server$` RPC MUST be validated at runtime with a schema library (such as Valibot or Zod) before executing database or privileged operations. - Data fetching across server boundaries MUST be orchestrated with `createAsync` or `createResource` combined with `cache` to enable deterministic SSR streaming and prevent hydration mismatches. - State mutations mutating server data SHOULD ALWAYS be wrapped in SolidStart's `action` primitive to enable automatic single-flight revalidations and declarative optimistic state updates. - Database clients, file system handles, and server secrets MUST NEVER be imported into isomorphic client components outside of explicit `.server.ts` modules or `server$` compilation scopes. ## Bad vs Good Implementations ### Server Function RPC with Runtime Validation and Action Orchestration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The `server$` function lexically captures the client signal `userId()`. When extracted into an HTTP RPC endpoint by Vinxi, the client signal is stripped from the server execution context, leading to undefined variables or runtime crashes. Additionally, input data is unvalidated, and direct invocation bypasses Solid's cache invalidation. ```typescript import { createSignal } from "solid-js"; import { server$ } from "@tanstack/start-server-functions"; // or @solidjs/start/server import db from "~/lib/db"; // Potential client bundle leak if not isolated export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); const [user, setUser] = createSignal<any>(null); // BAD: Capturing client signal 'userId()' inside server$ closure // BAD: Direct mutation without validation or action wrapper const updateProfile = server$(async (name: string) => { // Relies on lexically captured client state which will be undefined/stale on server invocation const id = userId(); return await db.user.update({ where: { id }, data: { name } }); }); return ( <button onClick={async () => { const updated = await updateProfile("New Name"); setUser(updated); }}> Update </button> ); } ``` #### Production Standard (Correct) > **Standard**: The good example dynamically imports server-only dependencies inside the server closure, preventing client bundle pollution. Input data is passed explicitly via standard FormData, parsed and validated at the boundary using Zod, and wrapped in `action` and `cache` primitives to trigger deterministic revalidation within a `<Suspense>` boundary. ```typescript import { action, json } from "@solidjs/router"; import { createAsync, cache } from "@solidjs/router"; import { Suspense, Show } from "solid-js"; import { z } from "zod"; const UpdateUserSchema = z.object({ userId: z.string().min(1), name: z.string().trim().min(2).max(100), }); // Type-safe RPC cached query boundary const getUser = cache(async (id: string) => { "use server"; const { getUserById } = await import("~/server/db.server"); return await getUserById(id); }, "getUser"); // Formal action mutation ensuring cache revalidation const updateUserAction = action(async (formData: FormData) => { "use server"; const { db } = await import("~/server/db.server"); const parsed = UpdateUserSchema.safeParse({ userId: formData.get("userId"), name: formData.get("name"), }); if (!parsed.success) { throw json({ errors: parsed.error.flatten().fieldErrors }, { status: 400 }); } const user = await db.user.update({ where: { id: parsed.data.userId }, data: { name: parsed.data.name }, }); return json({ success: true, user }); }); export default function UserProfile(props: { userId: string }) { const user = createAsync(() => getUser(props.userId)); return ( <Suspense fallback={<div>Loading profile...</div>}> <Show when={user()} fallback={<div>User not found</div>}> {(currentUser) => ( <form action={updateUserAction} method="post"> <input type="hidden" name="userId" value={currentUser().id} /> <input type="text" name="name" value={currentUser().name} required /> <button type="submit">Save Profile</button> </form> )} </Show> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Functions & Async Boundaries Production Standard

SolidStart 1.0 Server Functions & Async Boundaries Production Standard defines an industrial-grade behavioral standard for frontend engineering. SolidStart 1.0 relies on the Vinxi bundler to split `server$` closures into independent HTTP POST RPC endpoints. Direct lexical closure over client signals within `server$` scopes or failure to demarcate async boundaries with `<Suspense>` causes silent serialization failures, client-bundle secret leaks, and SSR hydration mismatches. Enforcing strict parameter passing, runtime input validation, and Solid async primitives maintains security and fine-grained reactivity across network 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$ RPCs or calling unvalidated server functions directly in reactive effects. 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$ RPCs or calling unvalidated server functions directly in reactive effects.	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:

Developers MUST NOT close over reactive client signals, component props, or client-side DOM state inside `server$` closures

Developers MUST NOT close over reactive client signals, component props, or client-side DOM state inside `server$` closures; all state MUST be passed explicitly 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.