SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation

--- description: SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation - Enforces strict structural boundaries between Solid's fine-grained client reactivity and SolidStart 1.0 Vinxi server$ RPC execution contexts. Eliminates closure captures across RPC boundaries, prevents direct raw server calls in tracking contexts, and mandates type-safe serialization with createAsync and query/cache primitives. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-functions-async-boundaries" --- # SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing over client signals inside server$ functions and triggering un-cached RPCs in reactive tracking scopes ## System Constraints You are a Principal Architect enforcing SolidStart 1.0 (Vinxi-based) server runtime and reactivity invariants. Your job is to strictly enforce boundaries between client signal graphs and server$ execution scopes. SolidStart compiles server$ calls into HTTP RPC endpoints; accessing client-side reactive state inside a server$ lexical closure causes silent capture of stale state, runtime serialization crashes, or security boundary breaches. You must ensure that all read operations are wrapped with router cache/query utilities, consumed via createAsync with an accessor parameter, mutations use createAction/action, and all server data transfers are strictly typed, serializable, and untainted by server secrets. ## Strict Guidelines - Engineers MUST ALWAYS pass client-side signal values as explicit, serializable arguments to server$ functions rather than accessing signal getters within the server$ closure. - Engineers MUST ALWAYS wrap data-fetching server$ functions with `query` (from `@solidjs/router`) or `cache` and consume them using `createAsync(() => queryFn(signal()))`. - Engineers MUST NOT invoke `server$` RPC functions directly inside JSX bodies or synchronous tracking scopes (`createEffect`, `createMemo`, `createComputed`) without an action or async resource wrapper. - Code SHOULD sanitize all return values from `server$` functions before sending to the client, explicitly excluding database handles, internal IDs, and sensitive environment keys. - Services MUST place server-only logic, database clients, and secrets into `*.server.ts` files or isolated `server$` blocks with explicit runtime environment verification. - Components NEVER destructure promises or access values from `createAsync` synchronously outside Suspense boundaries without null-checks or fallback handling. ## Bad vs Good Implementations ### Client Signal Capture in server$ RPC vs Explicit Parameter Query #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing `userId()` inside `server$` attempts to read a client-side reactive signal inside a remote server RPC execution environment. Compilers cannot serialize the reactive subscription over HTTP. Additionally, triggering raw server RPCs inside `createEffect` bypasses SolidStart's SSR hydration coordination, deduplication, and Suspense lifecycle. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start/server"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // ANTI-PATTERN: Lexical closure captures client signal inside server$ RPC. // This causes Vinxi serialization failures or binds to initial/stale client state. const fetchUserData = server$(async () => { const db = await import("~/server/db"); // Direct read of client signal inside server environment will fail or be undefined return db.default.user.findUnique({ where: { id: userId() } }); }); // ANTI-PATTERN: Directly calling raw server$ RPC inside createEffect createEffect(() => { fetchUserData().then((data) => console.log(data)); }); return <div>Loading...</div>; } ``` #### Production Standard (Correct) > **Standard**: The RPC function `getUserData` lives outside component scope and accepts an explicit serializable string parameter. Solid Router's `query` provides key-based caching, and `createAsync(() => getUserData(userId()))` properly establishes a fine-grained subscription to `userId()`, re-running the RPC cleanly when the signal updates while preserving SSR and Suspense semantics. ```typescript import { createSignal, Suspense, Show } from "solid-js"; import { query, createAsync } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; // GOOD: Define RPC boundary outside the component with explicit arguments const getUserData = query( server$(async (id: string) => { "use server"; if (!id || typeof id !== "string") { throw new Error("Invalid user ID parameter"); } const { default: db } = await import("~/server/db"); const user = await db.user.findUnique({ where: { id } }); if (!user) return null; // Return only safe serializable payload return { id: user.id, displayName: user.displayName, role: user.role }; }), "getUserData" ); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // GOOD: Feed reactive accessor directly into createAsync const user = createAsync(() => getUserData(userId())); return ( <Suspense fallback={<p>Loading user profile...</p>}> <Show when={user()} fallback={<p>User not found</p>}> {(u) => ( <div> <h1>{u().displayName}</h1> <span>Role: {u().role}</span> </div> )} </Show> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation

SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict structural boundaries between Solid's fine-grained client reactivity and SolidStart 1.0 Vinxi server$ RPC execution contexts. Eliminates closure captures across RPC boundaries, prevents direct raw server calls in tracking contexts, and mandates type-safe serialization with createAsync and query/cache primitives. 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: Closing over client signals inside server$ functions and triggering un-cached RPCs in reactive tracking scopes 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	Closing over client signals inside server$ functions and triggering un-cached RPCs in reactive tracking scopes	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-side signal values as explicit, serializable arguments to server$ functions rather than accessing signal getters within the server$ 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.