SolidStart 1.0 Server Function Boundary Isolation & Signal Tracking

--- description: SolidStart 1.0 Server Function Boundary Isolation & Signal Tracking - Mandates strict network and serialization boundary isolation for SolidStart 1.0 server$ functions and cache/createAsync primitives. Prevents client signal closure leakage into server boundaries, eliminates stale reactive closures, and guarantees deterministic hydration through mandatory Suspense boundaries. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-fn-boundary-isolation" --- # SolidStart 1.0 Server Function Boundary Isolation & Signal Tracking > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing over client signals inside server$ closures or omitting reactive accessor wrappers in createAsync ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 Server Function and Fine-Grained Reactive Boundary invariants. In SolidStart, server$ RPCs execute exclusively on the server runtime and cannot close over lexical client state, client signals, or DOM contexts. All parameters must be JSON-serializable, reactive dependencies must be tracked using accessor functions in createAsync, and components consuming async data must be wrapped in Suspense boundaries to avoid hydration mismatches and unhandled promise states. ## Strict Guidelines - Engineers MUST ALWAYS declare server$ functions at the module level or ensure they only receive serializable parameters rather than closing over client signals. - Engineers MUST ALWAYS wrap server function invocations in createAsync using a reactive accessor function (() => serverRpc(signal())) when dynamic arguments depend on signals. - Engineers MUST NOT attempt to read or mutate Solid signals, stores, or browser globals (window, document) inside a server$ closure. - Code MUST wrap any component or template consuming createAsync signals inside a <Suspense> boundary to guarantee streaming hydration integrity. - Services MUST utilize the cache() wrapper from @solidjs/router for deduplicated server-side data fetching and cache key invalidation with revalidate(). - Components NEVER invoke server$ mutations synchronously inside render scopes; mutations must be executed through action() or within user-triggered event handlers. ## Bad vs Good Implementations ### Server Function Parameter Passing & createAsync Reactive Binding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The server$ function closes over the client signal `userId`, which fails during compilation/RPC execution because client state cannot be implicitly captured across the network boundary. Additionally, passing `fetchUserData` directly into `createAsync` without an accessor function drops fine-grained reactivity, and rendering `user()` without a `<Suspense>` boundary causes hydration mismatches. ```typescript import { createSignal } from "solid-js"; import { createAsync } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; import { db } from "~/server/db"; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // ANTI-PATTERN: Closing over client signal inside server$ closure; // fails serialization and creates a disconnected lexical scope on the server const fetchUserData = server$(async () => { return db.user.findUnique({ where: { id: userId() } }); }); // ANTI-PATTERN: Calling fetcher directly without accessor; userId updates will not re-trigger const user = createAsync(fetchUserData); // ANTI-PATTERN: Missing <Suspense> boundary causes SSR/hydration mismatches return <div><h1>{user()?.name}</h1></div>; } ``` #### Production Standard (Correct) > **Standard**: The data fetcher is defined as an isolated cache() server function accepting serializable primitive arguments. The component passes an accessor function `() => getUserData(userId())` into `createAsync`, properly registering the signal dependency for reactive invalidation. A `<Suspense>` boundary wraps the consumer to maintain hydration consistency. ```typescript import { createSignal, Suspense } from "solid-js"; import { cache, createAsync } from "@solidjs/router"; import { db } from "~/server/db"; // CORRECT: Module-level cached server function accepting serializable arguments const getUserData = cache(async (id: string) => { "use server"; if (!id) return null; return db.user.findUnique({ where: { id } }); }, "getUserData"); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // CORRECT: Reactive accessor ensures createAsync re-runs when userId changes const user = createAsync(() => getUserData(userId())); return ( // CORRECT: Suspense boundary ensures proper streaming and SSR hydration <Suspense fallback={<p>Loading user profile...</p>}> <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 Function Boundary Isolation & Signal Tracking

SolidStart 1.0 Server Function Boundary Isolation & Signal Tracking defines an industrial-grade behavioral standard for frontend engineering. Mandates strict network and serialization boundary isolation for SolidStart 1.0 server$ functions and cache/createAsync primitives. Prevents client signal closure leakage into server boundaries, eliminates stale reactive closures, and guarantees deterministic hydration through mandatory Suspense boundaries. 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$ closures or omitting reactive accessor wrappers in createAsync 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$ closures or omitting reactive accessor wrappers in createAsync	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 at the module level or ensure they only receive serializable parameters rather than closing over client 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.