SolidStart 1.0 Server Function Isolation & Async Reactive Boundary Standard

--- description: SolidStart 1.0 Server Function Isolation & Async Reactive Boundary Standard - Enforces strict boundaries between client reactive graphs and Vinxi/Nitro RPC server execution in SolidStart 1.0. Prevents closure leaks over reactive signals, guarantees serialization integrity across HTTP RPC barriers, and mandates Suspense-wrapped createAsync consumption to eliminate hydration mismatches. 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-production-standard" --- # SolidStart 1.0 Server Function Isolation & Async Reactive Boundary Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Capturing Reactive Client Signals Inside server$ Closures or Calling RPCs Without createAsync & Suspense Isolation ## System Constraints You are a Principal Software Architect specializing in SolidJS and SolidStart 1.0 architectures. Your mission is to enforce the uncompromising separation between client reactive graphs and Nitro server$ execution contexts. You must ensure that server RPC boundaries never capture lexical client signals, serialize only strictly valid DTOs, safely isolate async operations using cache() and createAsync(), and ensure all async boundaries are enclosed by Suspense and ErrorBoundary components. ## Strict Guidelines - Engineers MUST NEVER access client-side reactive signals (e.g., accessor calls like `mySignal()`) inside the lexical scope of a `server$` function; arguments must be passed explicitly as serializable parameters at the callsite. - Engineers MUST consume read-only server data operations through `cache()` wrapped functions paired with `createAsync()`, ensuring continuous hydration streaming and automatic deduplication. - Engineers MUST wrap all `createAsync()` consuming components in both `<Suspense fallback={...}>` and `<ErrorBoundary fallback={...}>` boundaries to avoid hydration deadlocks and client-side unhandled promise rejections. - Engineers MUST NOT return non-serializable objects, raw database entity instances with private attributes, functions, or reactive signals from a `server$` RPC. - Engineers MUST execute mutations through `action()` wrappers or use `revalidate()` after invoking mutation server functions to guarantee deterministic client cache invalidation. - Code MUST strictly validate incoming `server$` RPC payloads on the server using a schema validation engine (such as Valibot or Zod) before performing data operations. ## Bad vs Good Implementations ### Querying Data Across Server Function Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing `userId()` inside the `server$` closure directly causes a compilation error or silent serialization failure because Vinxi splits the file into client and server bundles. Fetching inside `createEffect` without `createAsync` triggers waterfalls, causes hydration flicker, and bypasses Solid's streaming SSR capabilities. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start"; import { db } from "~/server/db"; export default function UserProfile() { const [userId] = createSignal("usr_123"); const [data, setData] = createSignal<any>(null); // ANTI-PATTERN: Capturing signal in server$ closure and manually managing async state in effect const fetchUser = server$(async () => { // Lexical signal capture fails or leaks client-server boundary return await db.user.findUnique({ where: { id: userId() } }); }); createEffect(async () => { const result = await fetchUser(); setData(result); }); return <div>{data() ? data().email : "Loading..."}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function `getUser` is isolated with `cache()`, validates input, and explicitly projects returned fields. The client invokes `getUser(userId())` reactively inside `createAsync`, which SolidStart handles properly during SSR streaming and client hydration when wrapped in `Suspense` and `ErrorBoundary`. ```typescript import { createSignal, Suspense, ErrorBoundary, type Component } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { db } from "~/server/db"; // GOOD: cache() groups deduplicated server RPC fetches const getUser = cache(async (id: string) => { "use server"; if (!id || typeof id !== "string") { throw new Error("Invalid user ID"); } const user = await db.user.findUnique({ where: { id }, select: { id: true, email: true, name: true } // Projection prevents leaking sensitive columns }); if (!user) throw new Error("User not found"); return user; }, "users"); const UserProfile: Component = () => { const [userId] = createSignal("usr_123"); // Pass signal accessor inside reactive tracking context of createAsync const user = createAsync(() => getUser(userId())); return ( <ErrorBoundary fallback={(err) => <div role="alert">{err.message}</div>}> <Suspense fallback={<div>Loading user profile...</div>}> <div> <h1>{user()?.name}</h1> <p>{user()?.email}</p> </div> </Suspense> </ErrorBoundary> ); }; export default UserProfile; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Function Isolation & Async Reactive Boundary Standard

SolidStart 1.0 Server Function Isolation & Async Reactive Boundary Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundaries between client reactive graphs and Vinxi/Nitro RPC server execution in SolidStart 1.0. Prevents closure leaks over reactive signals, guarantees serialization integrity across HTTP RPC barriers, and mandates Suspense-wrapped createAsync consumption to eliminate 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: Capturing Reactive Client Signals Inside server$ Closures or Calling RPCs Without createAsync & Suspense Isolation 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	Capturing Reactive Client Signals Inside server$ Closures or Calling RPCs Without createAsync & Suspense Isolation	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 NEVER access client-side reactive signals (e.g., accessor calls like `mySignal()`) inside the lexical scope of a `server$` function

Engineers MUST NEVER access client-side reactive signals (e.g., accessor calls like `mySignal()`) inside the lexical scope of a `server$` function; arguments must be passed explicitly as serializable parameters at the callsite.

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.