SolidStart 1.0 server$ RPC Boundaries and Reactive Async Invariants

--- description: SolidStart 1.0 server$ RPC Boundaries and Reactive Async Invariants - Mandates strict isolation between SolidStart 1.0 server functions (server$) and client-side reactive scopes. Enforces explicit parameter serialization, prevents closure leaks of reactive signals into server boundaries, and requires createAsync or cache wrappers to prevent Suspense boundary drops and hydration mismatches. 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-boundary-invariants" --- # SolidStart 1.0 server$ RPC Boundaries and Reactive Async Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing over client signals inside server$ RPCs or calling raw server functions in synchronous tracking contexts. ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 RPC and fine-grained reactivity architectural boundaries. SolidStart relies on compilation transforms (Vinxi/Babel) to extract server$(...) functions into HTTP POST RPC endpoints. You must reject any code where client signals or stores are captured via closure inside server$, mandate strict functional arguments with JSON/FormData serialization, and enforce createAsync or cache primitives for managing reactive asynchronous lifecycles across client/server transitions. ## Strict Guidelines - Engineers MUST ALWAYS declare server$ functions with explicit, serializable parameters instead of closing over client-side variables or signals. - Engineers MUST NOT access client signals, stores, or context accessors directly inside the body of a server$ closure. - Code MUST wrap reactive invocations of server$ data queries in createAsync() (or createResource()) coupled with a SolidJS <Suspense> boundary. - Code MUST supply an accessor function (() => signal()) to createAsync when server requests depend on reactive client values to maintain tracking subscriptions. - Components NEVER invoke raw asynchronous server$ promises directly within synchronous reactive primitives (such as createMemo or root body execution) without an asynchronous primitive boundary. ## Bad vs Good Implementations ### Violating RPC boundaries with closed-over client signals vs explicit parameterization with createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing userId() inside server$ creates an invalid boundary crossing because server$ executes in an isolated Node/runtime context where client memory heaps do not exist. Additionally, invoking an async RPC inside createMemo returns an unresolved Promise rather than integrating with Solid's fine-grained Suspense engine. ```typescript import { createSignal, createMemo } from "solid-js"; import { server$ } from "@solidjs/start"; export default function UserProfile() { const [userId, setUserId] = createSignal<string>("usr_123"); // ANTI-PATTERN: Capturing client-side signal `userId()` in server$ closure. // This throws a Vinxi serialization error at build-time or executes with stale closure bindings. // Furthermore, calling an async RPC inside createMemo fails to trigger Solid Suspense boundaries. const fetchUserData = server$(async () => { const id = userId(); // ERROR: Client reactive scope accessed on server return await db.users.findUnique({ where: { id } }); }); const user = createMemo(async () => { return await fetchUserData(); // ERROR: Raw promise inside createMemo causes race conditions & untracked UI tearing }); return <div>{user()?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function `getUserById` is completely decoupled and parameterized, accepting serializable data. On the client, `createAsync` receives a tracking accessor function `() => getUserById(userId())`, enabling fine-grained re-triggering whenever `userId` changes while properly suspending through `<Suspense>`. ```typescript import { createSignal, Suspense } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { server$ } from "@solidjs/start"; // CORRECT: server$ is a pure RPC accepting serializable primitive arguments const getUserById = cache(server$(async (id: string) => { "use server"; if (!id) throw new Error("User ID is required"); return await db.users.findUnique({ where: { id } }); }), "getUserById"); export default function UserProfile() { const [userId, setUserId] = createSignal<string>("usr_123"); // CORRECT: createAsync tracks the reactive accessor () => userId() // and automatically suspends the component tree until resolution. const user = createAsync(() => getUserById(userId())); return ( <Suspense fallback={<div>Loading profile...</div>}> <div> <h1>{user()?.name}</h1> <button onClick={() => setUserId("usr_456")}>Switch User</button> </div> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 server$ RPC Boundaries and Reactive Async Invariants

SolidStart 1.0 server$ RPC Boundaries and Reactive Async Invariants defines an industrial-grade behavioral standard for frontend engineering. Mandates strict isolation between SolidStart 1.0 server functions (server$) and client-side reactive scopes. Enforces explicit parameter serialization, prevents closure leaks of reactive signals into server boundaries, and requires createAsync or cache wrappers to prevent Suspense boundary drops and hydration mismatches. 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$ RPCs or calling raw server functions in synchronous tracking 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	Closing over client signals inside server$ RPCs or calling raw server functions in synchronous tracking 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 declare server$ functions with explicit, serializable parameters instead of closing over client-side variables or signals.

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.