SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Invariants

--- description: SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Invariants - Enforces strict RPC boundary isolation, serializable argument contracts, and proper Suspense integration in SolidStart 1.0. Prevents client-server closure leakage, hydration deadlocks, and silent reactive de-opt when crossing 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-server-function-async-boundaries" --- # SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Reactive Signal Closures into server$ RPCs and Executing Raw Server Promises Outside createAsync ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 RPC and reactivity guardrails. SolidStart compiles `server$` calls into standalone HTTP endpoints; reactive tracking scopes (Signals, Memos, Stores) cannot survive this serialization boundary. You must strictly mandate that all server functions consume explicit, JSON-serializable parameters, that asynchronous data flows into views exclusively via `createAsync` or router actions, and that all consumers are guarded by `<Suspense>` and `<ErrorBoundary>` boundaries to guarantee seamless hydration. ## Strict Guidelines - Engineers MUST ALWAYS wrap `server$` queries inside `cache()` and consume them via `createAsync(() => ...)` to maintain Solid's fine-grained tracking and enable SSR streaming. - Engineers MUST pass all client reactive values (signals, store slices) as explicit, evaluated primitives into the server function call; NEVER capture client signal accessors within a `server$` closure. - Engineers MUST ensure all arguments and return values of `server$` RPCs conform strictly to serializable data structures (primitives, plain objects, arrays, Date, or URL); NEVER pass functions, classes, DOM nodes, or Solid Proxies. - Components consuming async primitives MUST ALWAYS be bounded by both `<Suspense>` and `<ErrorBoundary>` to avoid unhandled promise deadlocks during hydration and server rendering. - Engineers MUST NOT execute bare `server$` promises directly within JSX rendering bodies or non-tracking components without reactive primitives managing their state lifecycle. ## Bad vs Good Implementations ### server$ Parameter Passing and createAsync Coordination #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Closing over `userId()` inside `server$` fails because the RPC function is extracted into a standalone server endpoint where the client-side reactive scope does not exist. Calling the server function as a raw promise outside `createAsync` breaks SSR streaming, hydration coordination, and fine-grained updates. ```typescript import { createSignal } from "solid-js"; import { server$ } from "@solidjs/start/server"; import { db } from "~/server/db"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // ANTI-PATTERN: Capturing client signal inside server$ closure; // invoking raw async RPC without createAsync or Suspense boundary. const fetchUser = server$(async () => { // Fails: userId signal accessor does not exist on the server worker return await db.user.findUnique({ where: { id: userId() } }); }); let user: any; fetchUser().then(res => { user = res; }); return <div>{user?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function accepts `id: string` as an explicit primitive argument and is wrapped in `cache()` for deduplication across the server and client. `createAsync` subscribes to `userId()` reactively and coordinates with `<Suspense>` and `<ErrorBoundary>` for glitch-free SSR and hydration. ```typescript import { createSignal, Suspense, ErrorBoundary } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; import { db } from "~/server/db"; // GOOD: server$ defined with explicit serializable arguments and cached for SSR deduplication const getUser = cache(server$(async (id: string) => { "use server"; if (!id || typeof id !== "string") { throw new Error("Invalid user ID"); } return await db.user.findUnique({ where: { id } }); }), "users"); export default function UserProfile() { const [userId, setUserId] = createSignal<string>("usr_123"); // Explicitly passing evaluated signal accessor into createAsync const user = createAsync(() => getUser(userId())); return ( <ErrorBoundary fallback={(err) => <p>Error loading profile: {err.message}</p>}> <Suspense fallback={<p>Loading user profile...</p>}> <div> <h1>{user()?.name}</h1> <button onClick={() => setUserId("usr_456")}>Switch User</button> </div> </Suspense> </ErrorBoundary> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Invariants

SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict RPC boundary isolation, serializable argument contracts, and proper Suspense integration in SolidStart 1.0. Prevents client-server closure leakage, hydration deadlocks, and silent reactive de-opt when crossing 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: Leaking Reactive Signal Closures into server$ RPCs and Executing Raw Server Promises Outside 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	Leaking Reactive Signal Closures into server$ RPCs and Executing Raw Server Promises Outside 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 ALWAYS wrap `server$` queries inside `cache()` and consume them via `createAsync(() => ...)` to maintain Solid's fine-grained tracking and enable SSR streaming.

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.