SolidStart 1.0 Server Function Serialization and Async Boundary Guardrails

--- description: SolidStart 1.0 Server Function Serialization and Async Boundary Guardrails - Enforces strict isolation between client reactive signal graphs and SolidStart 1.0 server$ RPC functions. Prevents bundling leaks, closure state corruption, and silent reactivity failures by requiring explicit serializable arguments, validation schemas, and createAsync tracking wrappers. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-function-boundaries" --- # SolidStart 1.0 Server Function Serialization and Async Boundary Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Accessing Client Signals Directly in server$ Closures and Calling RPCs Without createAsync ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions & Async Boundaries. Mandate strict client/server boundary contracts, input serialization validation, and reactive integration via createAsync. ## Strict Guidelines - Engineers MUST NOT access client signals, stores, or client-side component state directly within a server$ function body closure. - Engineers MUST explicitly pass signal values as serializable arguments into server$ RPC functions from the client context. - Engineers MUST wrap reactive server-side data fetching in createAsync(() => serverFn(signal())) to ensure Solid tracking context tracks client dependencies. - Engineers MUST validate all arguments passed to server$ RPCs using runtime schema validators (e.g., Zod, Valibot) before executing privileged business logic. - Components consuming createAsync data MUST ALWAYS be enclosed within <Suspense> and <ErrorBoundary> boundaries to support streaming SSR and graceful degradation. - Server actions modifying state MUST use action(server$(...)) or explicitly revalidate cached router data using query/cache invalidation utilities. ## Bad vs Good Implementations ### Client Signal Leakage into server$ vs Parameterized RPC with createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Client signals cannot be read inside server$ closures because server$ runs in an isolated Node/worker context without access to the client reactive root. Calling an RPC imperatively inside the component body executes during every render tick without Solid tracking context, breaking Suspense integration. ```typescript import { createSignal } from "solid-js"; import { server$ } from "@solidjs/start/server"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // CRITICAL BUG: Direct access of client signal `userId()` inside server$ closure // This causes bundling errors or compiles into an undefined execution on the server RPC. const fetchUser = server$(async () => { const id = userId(); // Fails at runtime across RPC wire return await db.user.findUnique({ where: { id } }); }); // CRITICAL BUG: Unwrapped raw RPC call outside createAsync loses reactivity and streaming const user = fetchUser(); return <div>{user?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server$ RPC accepts explicit serializable parameters, runs server-side input validation, and is invoked via createAsync within the client tracking scope. Solid's fine-grained reactivity tracks userId() updates on the client and triggers automated refetches under the Suspense boundary. ```typescript import { createSignal, Suspense } from "solid-js"; import { server$ } from "@solidjs/start/server"; import { createAsync } from "@solidjs/router"; import { z } from "zod"; import { db } from "~/server/db"; const UserIdSchema = z.string().min(1); // RPC is defined with explicit serializable parameters and schema validation const getUserById = server$(async (id: string) => { "use server"; const validatedId = UserIdSchema.parse(id); return await db.user.findUnique({ where: { id: validatedId } }); }); export default function UserProfile() { const [userId, setUserId] = createSignal<string>("usr_123"); // Reactive tracking occurs on the client via createAsync; RPC receives plain serializable value const user = createAsync(() => getUserById(userId())); return ( <Suspense fallback={<p>Loading user profile...</p>}> <div>{user()?.name}</div> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Function Serialization and Async Boundary Guardrails

SolidStart 1.0 Server Function Serialization and Async Boundary Guardrails defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between client reactive signal graphs and SolidStart 1.0 server$ RPC functions. Prevents bundling leaks, closure state corruption, and silent reactivity failures by requiring explicit serializable arguments, validation schemas, and createAsync tracking wrappers. 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: Accessing Client Signals Directly in server$ Closures and Calling RPCs Without 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	Accessing Client Signals Directly in server$ Closures and Calling RPCs Without 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 NOT access client signals, stores, or client-side component state directly within a server$ function body closure.

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.