SolidStart 1.0 Server Functions & Async Reactive Boundary Invariants

--- description: SolidStart 1.0 Server Functions & Async Reactive Boundary Invariants - Enforces strict isolation between client-side reactive signal graphs and SolidStart server$ RPC primitives. Prohibits lexical capture of reactive getters inside server closures, mandates JSON-serializable RPC parameter passing, and requires wrapping asynchronous data retrieval in createAsync within Suspense and ErrorBoundary contexts. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-fn-async-boundary-guardrail" --- # SolidStart 1.0 Server Functions & Async Reactive Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Capturing Client Signals in server$ Closures or Calling RPCs Without createAsync & Suspense Boundaries ## System Constraints You are a Principal Engineer enforcing architectural invariants for SolidStart 1.0 server functions and reactive async boundaries. You must reject any lexical signal capture within server$ functions, eliminate unhandled async promises outside createAsync, prevent non-serializable RPC payload passing, and mandate comprehensive Suspense and ErrorBoundary containment across all client/server data transitions. ## Strict Guidelines - Engineers MUST ALWAYS pass client state as explicit, JSON-serializable arguments to server$ functions rather than capturing signals or accessors via lexical closure. - Engineers MUST wrap all read-only server$ invocations in `createAsync` or `query` to bind RPC lifecycles into Solid's reactive tracking and Suspense coordination graph. - Engineers MUST NOT invoke server$ functions inside `createEffect` to synchronize local signals; mutations must use `action` or `useAction` coupled with reactive invalidation via `revalidate`. - Components rendering asynchronous resources derived from server$ MUST be enclosed in both `<Suspense fallback={...}>` and `<ErrorBoundary fallback={...}>` to prevent hydration mismatches and unhandled SSR promise rejections. - Engineers MUST NEVER return non-serializable entities (such as class instances, Symbols, DOM nodes, or functions/Signals) across the server$ RPC boundary. - Services exposing server$ RPC endpoints MUST enforce server-side authentication, authorization, and input validation schemas (e.g., Valibot, Zod) independently of client-side validation. ## Bad vs Good Implementations ### Anti-Pattern: Lexical Signal Capture & Detached server$ Execution in Effects #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing a client-side signal getter (userId()) within a server$ function body fails because server code runs in an isolated Node/runtime context without access to client reactive scopes. Additionally, managing asynchronous fetching manually via createEffect and secondary signals breaks SolidStart SSR hydration, introduces race conditions, and bypasses Solid's Suspense tree. ```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); // CRITICAL BUG: Lexical capture of client signal inside server$ closure // and calling untracked RPC inside createEffect causing race conditions const fetchUser = server$(async () => { // userId() is not reactive across the RPC serialization boundary! return await db.user.findUnique({ where: { id: userId() } }); }); createEffect(() => { fetchUser().then((data) => setUserData(data)); }); return <div>{userData() ? userData().name : 'Loading...'}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function receives the ID as a pure, serializable argument. The query/createAsync primitive integrates the RPC lifecycle into Solid's fine-grained reactivity and concurrent scheduler. Wrapping the component output in <Suspense> and <ErrorBoundary> guarantees full SSR streaming compatibility and deterministic client hydration. ```typescript import { createSignal, Suspense, ErrorBoundary } from 'solid-js'; import { query, createAsync } from '@solidjs/router'; import { server$ } from '@solidjs/start/server'; // Type-safe, isolated server RPC with explicit serializable input const getUserById = query(server$(async (id: string) => { 'use server'; if (!id || typeof id !== 'string') { throw new Error('Invalid user ID parameter.'); } const user = await db.user.findUnique({ where: { id } }); if (!user) throw new Error('User not found'); return { id: user.id, name: user.name }; }), 'getUserById'); export default function UserProfile() { const [userId, setUserId] = createSignal('usr_123'); // createAsync binds the reactive accessor to the RPC call cleanly const user = createAsync(() => getUserById(userId())); return ( <ErrorBoundary fallback={(err) => <div role="alert">Error: {err.message}</div>}> <Suspense fallback={<div>Loading user profile...</div>}> <div>{user()?.name}</div> </Suspense> </ErrorBoundary> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Functions & Async Reactive Boundary Invariants

SolidStart 1.0 Server Functions & Async Reactive Boundary Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between client-side reactive signal graphs and SolidStart server$ RPC primitives. Prohibits lexical capture of reactive getters inside server closures, mandates JSON-serializable RPC parameter passing, and requires wrapping asynchronous data retrieval in createAsync within Suspense and ErrorBoundary contexts. 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 Client Signals in server$ Closures or Calling RPCs Without createAsync & Suspense Boundaries 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 Client Signals in server$ Closures or Calling RPCs Without createAsync & Suspense Boundaries	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 pass client state as explicit, JSON-serializable arguments to server$ functions rather than capturing signals or accessors via lexical 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.