SolidStart 1.0 Server Functions & Reactive Async Boundary Invariants

--- description: SolidStart 1.0 Server Functions & Reactive Async Boundary Invariants - Enforces strict isolation between client-side SolidJS signals and server-side RPC execution boundaries instantiated via server$, cache, or action. Signal accessors must never be embedded directly within server function closures, and server queries must be declared with createAsync using reactive accessor parameters to prevent hydration mismatches, serialization failures, and broken dependency tracking. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-function-reactivity-boundary" --- # SolidStart 1.0 Server Functions & Reactive Async Boundary Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Capturing Client Signals Directly in server$ Closures and Omitting createAsync Reactive Contexts ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions and Async Boundaries. Mandate strict boundary isolation between Nitro/Vinxi server execution contexts and fine-grained client reactivity. Ensure server functions are pure RPC boundaries that receive serialized arguments, execute outside the client reactive graph, and integrate safely with Suspense via createAsync or action. ## Strict Guidelines - Engineers MUST ALWAYS invoke server RPC functions through `createAsync(() => serverFn(signal()))` when tracking reactive signals on the client. - Engineers MUST NOT reference client-side signals, store accessors, or browser globals directly within the lexical scope of a `server$` closure. - Engineers MUST declare reusable server functions (`server$`, `cache`, `action`) at module scope or in dedicated `*.server.ts` files to prevent unintended closure serialization over local component scope. - Code SHOULD validate and sanitize every argument passed into `server$` using schemas (e.g., Zod, Valibot) before executing database or internal service logic. - Services MUST leverage `action` and `submission` signals or `cache` invalidation (`revalidate`) for server state mutations instead of manual client-side effect loops. - Components NEVER render `createAsync` accessors without an enclosing `<Suspense>` boundary to avoid premature null dereferences and hydration mismatch. ## Bad vs Good Implementations ### Signal tracking across server$ RPC boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing the client signal `userId()` inside the `server$` closure causes bundling/serialization failure or server runtime reference errors. Calling the async server function inside `createEffect` bypasses Solid's fine-grained async Suspense coordination, leading to hydration flicker and potential race conditions. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start"; import { db } from "~/server/db"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); const [userData, setUserData] = createSignal<any>(null); // ANTI-PATTERN: Capturing signal inside server$ closure and // attempting to manually manage async fetch state in createEffect const fetchUser = server$(async () => { // userId() is not available on server or breaks closure serialization return await db.user.findUnique({ where: { id: userId() } }); }); createEffect(async () => { const data = await fetchUser(); setUserData(data); }); return <div>{userData()?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function is declared at module scope, accepts explicit primitives, and validates input via Zod. The client tracks the `userId` signal reactively using `createAsync(() => getUser(userId()))`, enabling automatic re-fetching upon signal change and seamless Suspense integration during SSR and hydration. ```typescript import { createSignal, Suspense } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { server$ } from "@solidjs/start"; import { z } from "zod"; import { db } from "~/server/db"; const UserIdSchema = z.string().min(1); // Module-scoped server query wrapped in cache with input validation const getUser = cache(server$(async (id: string) => { "use server"; const validatedId = UserIdSchema.parse(id); const user = await db.user.findUnique({ where: { id: validatedId } }); if (!user) throw new Error("User not found"); return user; }), "users"); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // Explicitly pass signal value inside createAsync accessor for reactive re-fetching const user = createAsync(() => getUser(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 Functions & Reactive Async Boundary Invariants

SolidStart 1.0 Server Functions & Reactive Async Boundary Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between client-side SolidJS signals and server-side RPC execution boundaries instantiated via server$, cache, or action. Signal accessors must never be embedded directly within server function closures, and server queries must be declared with createAsync using reactive accessor parameters to prevent hydration mismatches, serialization failures, and broken dependency tracking. 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 Directly in server$ Closures and Omitting createAsync Reactive 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 Client Signals Directly in server$ Closures and Omitting createAsync Reactive 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 invoke server RPC functions through `createAsync(() => serverFn(signal()))` when tracking reactive signals on the client.

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.