SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation Standard

--- description: SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation Standard - Enforces strict isolation between fine-grained reactive client signals and SolidStart 1.0 server$ RPC boundaries. Prevents signal serialization failures, hydration deadlocks, and silent reactivity loss across the wire by mandating cache(), createAsync, and explicit boundary serialization. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-rpc-async-boundaries" --- # SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Invoking server$ directly within createEffect or capturing reactive signals inside server$ closures ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 Server Functions and Async Boundary safety. You strictly enforce that SolidJS signals cannot cross the wire into server$ closures, server RPCs must be orchestrated via cache() and createAsync(), and all async dependencies must be encapsulated within Suspense boundaries to safeguard SSR hydration. ## Strict Guidelines - Engineers MUST ALWAYS wrap server-read RPC queries in cache() and ingest them via createAsync() to ensure SSR streaming compatibility and eliminate hydration waterfalls. - Engineers MUST NOT reference or call reactive signals directly within the lexical scope of a server$ closure; all reactive values must be resolved on the client and passed as explicit serializable parameters. - Engineers MUST wrap all components consuming createAsync accessors in a Suspense boundary with an explicit fallback to prevent SSR hydration desynchronization. - Engineers MUST mutate server state using action() or useSubmission() rather than ad-hoc server$ invocations within createEffect or client lifecycle hooks. - Code MUST return purely serializable JSON-compatible payloads from server$ calls; class instances, raw streams, or functions must not cross the RPC boundary without custom serializer transforms. - Components NEVER import Node.js server dependencies or database clients outside of server$ lexical boundaries or .server.ts file modules. ## Bad vs Good Implementations ### Direct server$ Call Inside createEffect with Closed-Over Signal vs cache() + createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing userId() inside the server$ closure fails because server$ executes in an isolated Node/Nitro runtime where the client-side reactive context does not exist. Triggering raw server$ calls in createEffect produces client-side waterfalls, hydration mismatches, and fails to integrate with SSR streaming. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start/server"; const [userId, setUserId] = createSignal("usr_123"); const [userData, setUserData] = createSignal<any>(null); // ANTI-PATTERN: Capturing signal inside server$ closure and executing RPC inside createEffect. // This breaks fine-grained tracking, creates SSR race conditions, and bypasses Solid hydration cache. const fetchUser = server$(async () => { // Accessing reactive signal directly across server boundary is undefined or captures stale initial state return await db.user.findUnique({ where: { id: userId() } }); }); export default function UserProfile() { createEffect(async () => { const data = await fetchUser(); setUserData(data); }); return <div>{userData() ? userData().name : "Loading..."}</div>; } ``` #### Production Standard (Correct) > **Standard**: The RPC is registered as a cacheable query via Solid Router's query() (or cache()), accepting explicit arguments. createAsync reactively tracks userId() on the client, invokes the RPC properly across the boundary, reuses SSR cached data during hydration, and coordinates seamlessly with Suspense. ```typescript import { createSignal, Suspense } from "solid-js"; import { query, createAsync } from "@solidjs/router"; // GOOD: Define cached server query accepting explicit serializable arguments const getUser = query(async (id: string) => { "use server"; if (!id) return null; return await db.user.findUnique({ where: { id }, select: { id: true, name: true, email: true } }); }, "getUser"); export default function UserProfile() { const [userId] = createSignal("usr_123"); // Accessor is tracked reactively: when userId() updates, createAsync refetches via RPC const user = createAsync(() => getUser(userId())); return ( <Suspense fallback={<div>Loading user profile...</div>}> <div>{user()?.name}</div> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

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

SolidStart 1.0 server$ RPC & Async Boundary Reactive Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between fine-grained reactive client signals and SolidStart 1.0 server$ RPC boundaries. Prevents signal serialization failures, hydration deadlocks, and silent reactivity loss across the wire by mandating cache(), createAsync, and explicit boundary serialization. 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: Invoking server$ directly within createEffect or capturing reactive signals inside server$ closures 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	Invoking server$ directly within createEffect or capturing reactive signals inside server$ closures	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-read RPC queries in cache() and ingest them via createAsync() to ensure SSR streaming compatibility and eliminate hydration waterfalls.

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.