SolidStart 1.0 server$ RPC Boundaries and Fine-Grained Reactive Isolation

--- description: SolidStart 1.0 server$ RPC Boundaries and Fine-Grained Reactive Isolation - Enforces strict lexical and serialization boundaries when authoring SolidStart server$ RPCs and integrating them with fine-grained reactivity. Prohibits closing over client-side signals inside server functions and mandates explicit argument serialization, query/action wrapping, and Suspense boundary containment. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-rpc-signal-boundary" --- # SolidStart 1.0 server$ RPC Boundaries and Fine-Grained Reactive Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing Over Client Signals Inside server$ Functions and Bypassing Suspense Boundaries ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 architectural invariants. You must prevent compiler-boundary leaks and runtime crashes caused by mixing client-side fine-grained reactive primitives (signals, stores, memos) into server$ RPC closures. SolidStart extracts server$ bodies into isolated HTTP RPC endpoints via Vinxi; closing over client state causes serialization corruption, reference errors, and hydration desynchronization. Enforce strict parameterization, cache/query decorators, createAsync data access, and mandatory Suspense wrappers. ## Strict Guidelines - Engineers MUST ALWAYS pass signal values as explicit, primitive/serializable arguments to server$ functions rather than referencing client signals inside the server$ closure. - Engineers MUST NOT reference outer client-scoped variables, signals, stores, or DOM references within the lexical body of a server$ function. - Engineers MUST wrap read-oriented server$ calls using query() or cache() from @solidjs/router and consume them via createAsync() to preserve fine-grained reactivity and SSR streaming. - Engineers MUST wrap mutation-oriented server$ calls using action() from @solidjs/router or explicit event handlers rather than calling RPCs inside untracked lifecycle hooks. - Components MUST wrap all createAsync accessor evaluations within <Suspense> and <ErrorBoundary> to prevent hydration mismatch during SSR and streaming. - Engineers MUST ensure all arguments and return values crossing the server$ boundary conform to serializable payloads (primitives, plain objects, arrays, Date, or URL instances). ## Bad vs Good Implementations ### Lexical Signal Leak vs. Explicit Parameterization with createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Referencing the client-side 'userId' signal inside server$ fails because the compiler splits the function into an isolated RPC endpoint where client lexical scopes do not exist. Furthermore, fetching in onMount and manual signal assignment bypasses SSR streaming and Suspense. ```typescript import { createSignal, onMount } from 'solid-js'; import { server$ } from '@solidjs/start/server'; export default function UserProfile() { const [userId, setUserId] = createSignal('usr_123'); const [user, setUser] = createSignal<any>(null); // CRITICAL ANTI-PATTERN: Closure captures client signal 'userId' // Vinxi extracts this function to a server RPC where 'userId' is undefined. const fetchUserData = server$(async () => { const id = userId(); // Runtime error on server; closure is stripped const db = await import('~/server/db'); return db.users.findUnique({ where: { id } }); }); onMount(async () => { // Bypasses SolidStart Suspense pipeline and creates client-side fetch cascade const data = await fetchUserData(); setUser(data); }); return <div>{user() ? user().name : 'Loading...'}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function accepts an explicit parameter and is isolated using query(). The client component tracks userId() in the createAsync accessor, cleanly bridging Solid's reactive graph to the server RPC while Suspense handles streaming and hydration seamlessly. ```typescript import { createSignal, Suspense, ErrorBoundary, type Component } from 'solid-js'; import { query, createAsync } from '@solidjs/router'; // Explicitly parameterized server function wrapped in query cache const getUserData = query(async (id: string) => { 'use server'; if (!id || typeof id !== 'string') { throw new Error('Invalid user ID parameter'); } const db = await import('~/server/db'); const user = await db.users.findUnique({ where: { id } }); if (!user) throw new Error('User not found'); return user; }, 'getUserData'); const UserProfile: Component = () => { const [userId, setUserId] = createSignal('usr_123'); // Signal evaluated in client tracking scope and passed explicitly const user = createAsync(() => getUserData(userId())); return ( <ErrorBoundary fallback={(err) => <p role="alert">Error: {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> ); }; export default UserProfile; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 server$ RPC Boundaries and Fine-Grained Reactive Isolation

SolidStart 1.0 server$ RPC Boundaries and Fine-Grained Reactive Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict lexical and serialization boundaries when authoring SolidStart server$ RPCs and integrating them with fine-grained reactivity. Prohibits closing over client-side signals inside server functions and mandates explicit argument serialization, query/action wrapping, and Suspense boundary containment. 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 Bypassing Suspense Boundaries 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 Bypassing Suspense Boundaries	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 signal values as explicit, primitive/serializable arguments to server$ functions rather than referencing client signals inside 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.