SolidStart 1.0 Server Functions and Async Boundary Invariants

--- description: SolidStart 1.0 Server Functions and Async Boundary Invariants - Enforces strict isolation of reactive state and runtime boundaries across SolidStart server$ RPC calls and async primitives. Prevents client-side lexical scope leakage into server environments, serialization bugs, and broken fine-grained reactivity when bridging signals with asynchronous RPC executions. 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-guardrail" --- # SolidStart 1.0 Server Functions and Async Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Capturing Reactive Signals Directly in server$ Lexical Closures or Destructuring Async Responses Outside Suspense Contexts ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 architectural invariants. You must prevent lexical leakage across client/server RPC boundaries and guarantee correct fine-grained signal tracking across async transitions. ## Strict Guidelines - Engineers MUST ALWAYS declare 'server$' functions with explicit, serializable parameters instead of closing over client-side reactive state or module variables. - Engineers MUST NOT reference client-side signals, stores, or DOM APIs inside the body of a 'server$' function. - Code MUST pass signal values explicitly at invocation time within reactive contexts (such as 'createAsync' or effects) rather than passing accessors into RPC boundaries. - Components consuming async server data MUST ALWAYS be wrapped in '<Suspense>' and '<ErrorBoundary>' primitives to prevent hydration mismatch and unhandled promise crashes. - Services exposing 'server$' endpoints MUST validate and sanitize all deserialized incoming arguments using runtime schema validators (e.g., Valibot, Zod) before executing database or internal business operations. - Engineers MUST NOT destructure properties directly from 'createAsync' returns before the promise resolves, preserving fine-grained accessor reactivity. ## Bad vs Good Implementations ### Invoking server$ functions with explicit signal values via createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: SolidStart extracts server$ functions into standalone HTTP RPC endpoints at build time via Vinxi. Accessing client signals inside the server$ closure fails at runtime because client lexical variables do not exist in the isolated server environment. ```typescript import { createSignal, createComponent } from 'solid-js'; import { server$ } from '@solidjs/start/server'; import { db } from '~/lib/db'; export function UserProfile() { const [userId, setUserId] = createSignal('usr_123'); // BAD: Accessing reactive signal inside the lexical closure of server$ // This causes compiler extraction failure, runtime reference errors on the server, // and leaks private closure context across the network boundary. const fetchUserData = server$(async () => { return await db.user.findUnique({ where: { id: userId() } }); }); return ( <div> <button onClick={() => fetchUserData()}>Load</button> </div> ); } ``` #### Production Standard (Correct) > **Standard**: The server$ function is declared with explicit parameters and runtime validation. The client tracks the signal reactively via createAsync, passing the current evaluated value to the RPC, and wraps consumption within Suspense and ErrorBoundary boundaries. ```typescript import { createSignal, Suspense, ErrorBoundary } from 'solid-js'; import { server$ } from '@solidjs/start/server'; import { createAsync } from '@solidjs/router'; import { z } from 'zod'; import { db } from '~/lib/db'; // GOOD: server$ declared with explicit serializable input and validation const getUserById = server$(async (id: string) => { const parsedId = z.string().min(1).parse(id); const user = await db.user.findUnique({ where: { id: parsedId } }); if (!user) throw new Error('User not found'); return { id: user.id, name: user.name, email: user.email }; }); export function UserProfile() { const [userId, setUserId] = createSignal('usr_123'); // Track signal reactively on the client and pass evaluated value to the RPC const user = createAsync(() => getUserById(userId())); return ( <ErrorBoundary fallback={(err) => <p class="error">{err.message}</p>}> <Suspense fallback={<p>Loading profile...</p>}> <div> <h1>{user()?.name}</h1> <p>{user()?.email}</p> </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 isolation of reactive state and runtime boundaries across SolidStart server$ RPC calls and async primitives. Prevents client-side lexical scope leakage into server environments, serialization bugs, and broken fine-grained reactivity when bridging signals with asynchronous RPC executions. 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: Capturing Reactive Signals Directly in server$ Lexical Closures or Destructuring Async Responses Outside Suspense Contexts 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	Capturing Reactive Signals Directly in server$ Lexical Closures or Destructuring Async Responses Outside Suspense Contexts	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 declare 'server$' functions with explicit, serializable parameters instead of closing over client-side reactive state or module variables.

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.