SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Async Boundaries

--- description: SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Async Boundaries - Mandates strict serialization integrity, reactive decoupling, and proper async boundary usage when executing SolidStart 1.0 server$ RPC functions. Prevents reactive closure capture, non-serializable payload passing across Nitro RPC bridges, and unhandled async state during SSR hydration. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-fn-boundary-guardrail" --- # SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Async Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Client Signals into Server Closures and Bypassing Suspense Hydration Boundaries ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 RPC invariants. SolidStart server functions (server$) run in an isolated server context (Nitro/Vite runtime) and communicate via HTTP POST RPCs. Fine-grained SolidJS reactivity exists solely in the client runtime or during initial SSR component rendering. You must strictly forbid capturing reactive signals, props, or client-scoped state directly inside server$ closures. Enforce explicit argument passing of JSON-serializable primitives and integration with createAsync, query/cache, and Suspense boundaries. ## Strict Guidelines - Engineers MUST ALWAYS pass signals into server$ functions as resolved, plain JSON-serializable argument primitives at the call site (e.g., serverFn(query())). - Engineers MUST NOT access client signals, accessors, store proxies, or component props inside the closure body of server$ or 'use server' functions. - Engineers MUST NEVER return non-serializable entities (DOM nodes, functions, class instances, Symbols, circular structures) across the server$ boundary. - Components reading async server$ operations MUST ALWAYS wrap data consumption with SolidStart's createAsync or resource primitives combined with <Suspense> and <ErrorBoundary>. - Data mutation operations executed via server$ MUST utilize SolidStart actions (action(server$(...))) to guarantee proper cache invalidation and transition state management. - Engineers MUST NOT invoke server$ RPC calls nakedly within createEffect or render loops without an async coordinator, preventing request waterfalls and hydration race conditions. ## Bad vs Good Implementations ### Resolving Reactive State into server$ RPC with Suspense Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing query() inside server$ creates an invalid closure that fails across client/server boundaries. Calling searchUsers() nakedly in a createEffect introduces out-of-order race conditions, ignores hydration coordination, and skips error handling. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start/server"; import { db } from "~/server/db"; export default function UserSearch() { const [query, setQuery] = createSignal(""); const [results, setResults] = createSignal<any[]>([]); // ANTI-PATTERN: Capturing signal inside server$ closure, naked invocation in effect, // and omitting Suspense/ErrorBoundary boundaries causing hydration mismatches. const searchUsers = server$(async () => { // RUNTIME FAILS: 'query' accessor is not defined on the server worker return await db.user.findMany({ where: { name: { contains: query() } } }); }); createEffect(() => { // Waterfall and uncontrolled race condition across network boundary searchUsers().then(setResults); }); return ( <div> <input value={query()} onInput={(e) => setQuery(e.currentTarget.value)} /> <ul>{results().map(u => <li>{u.name}</li>)}</ul> </div> ); } ``` #### Production Standard (Correct) > **Standard**: The server function accepts an explicit serializable argument. The client tracks the query signal reactively inside createAsync, passing resolved primitive values. Async boundaries (<Suspense> and <ErrorBoundary>) handle SSR streaming and client hydration flawlessly. ```typescript import { createSignal, Suspense, ErrorBoundary, For } from "solid-js"; import { server$ } from "@solidjs/start/server"; import { createAsync } from "@solidjs/router"; import { db } from "~/server/db"; // Pure server RPC receiving serializable parameters const searchUsers = server$(async (searchQuery: string) => { "use server"; if (typeof searchQuery !== "string") { throw new Error("Invalid input"); } return await db.user.findMany({ where: { name: { contains: searchQuery } }, select: { id: true, name: true } }); }); export default function UserSearch() { const [query, setQuery] = createSignal(""); // createAsync tracks query() reactively and integrates with Suspense/Transitions const users = createAsync(() => searchUsers(query())); return ( <div> <input type="text" value={query()} onInput={(e) => setQuery(e.currentTarget.value)} placeholder="Search users..." /> <ErrorBoundary fallback={(err) => <p role="alert">Search failed: {err.message}</p>}> <Suspense fallback={<p>Searching directory...</p>}> <ul> <For each={users()}> {(user) => <li>{user.name}</li>} </For> </ul> </Suspense> </ErrorBoundary> </div> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Async Boundaries

SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Async Boundaries defines an industrial-grade behavioral standard for frontend engineering. Mandates strict serialization integrity, reactive decoupling, and proper async boundary usage when executing SolidStart 1.0 server$ RPC functions. Prevents reactive closure capture, non-serializable payload passing across Nitro RPC bridges, and unhandled async state during SSR hydration. 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: Leaking Client Signals into Server Closures and Bypassing Suspense Hydration 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	Leaking Client Signals into Server Closures and Bypassing Suspense Hydration 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 signals into server$ functions as resolved, plain JSON-serializable argument primitives at the call site (e.g., serverFn(query())).

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.