SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Boundaries

SolidStart 1.0 utilizes Vinxi-driven compilation to transform `server$` calls into JSON RPC endpoints, executing purely on the server while client-side signals remain isolated to the client runtime. Engineers must never close over client-side reactive primitives (signals, stores, memo hooks) inside `server$` bodies, nor expose unvalidated inputs across serialized RPC invocations. Furthermore, asynchronous server data transitions must be coordinated with `cache`, `createAsync`, and `Suspense` rather than embedding manual async effects inside component render scopes.

--- description: SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Boundaries - SolidStart 1.0 utilizes Vinxi-driven compilation to transform `server$` calls into JSON RPC endpoints, executing purely on the server while client-side signals remain isolated to the client runtime. Engineers must never close over client-side reactive primitives (signals, stores, memo hooks) inside `server$` bodies, nor expose unvalidated inputs across serialized RPC invocations. Furthermore, asynchronous server data transitions must be coordinated with `cache`, `createAsync`, and `Suspense` rather than embedding manual async effects inside component render scopes. 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-guardrail" --- # SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing Over Client Signals in server$ Closures or Calling Async RPCs Inside Untracked Reactive Render Loops ## System Constraints You are a Principal Engineer enforcing strict SolidStart 1.0 architectural guardrails. Enforce complete isolation between Vinxi-compiled server RPC boundaries (`server$`) and SolidJS client reactive roots. Prevent leaking reactive state across serialization boundaries, prevent raw server calls inside render bodies without `createAsync`/`cache`, mandate runtime schema validation with libraries such as Valibot or Zod inside server functions, and ensure strict error boundary handling. ## Strict Guidelines - Engineers MUST ALWAYS treat `server$` boundaries as remote, untrusted RPC endpoints and parse all incoming parameters using strict schema validators (e.g., Zod, Valibot). - Engineers MUST NOT reference or close over outer component scope variables, signals, or reactive stores within a `server$` body; pass all state as explicit serializable arguments. - Engineers MUST wrap read-only server data fetchers in `cache()` and ingest them via `createAsync()` to ensure proper SSR serialization, deduplication, and `Suspense` tracking. - Engineers MUST NOT execute raw asynchronous server function calls directly in top-level component render functions or synchronous JSX bindings; use actions (`createAsyncStore`, `useAction`, or form submissions) for mutations. - Engineers MUST NEVER return non-serializable objects (functions, circular references, Symbol-keyed objects, unmanaged native streams) across the `server$` boundary. - Engineers MUST ensure every `createAsync` invocation is backed by a `<Suspense>` and `<ErrorBoundary>` boundary to prevent uncaught promise rejection cascades during SSR. ## Bad vs Good Implementations ### Closing Over Reactive State vs. Explicit Serialized Arguments with Schema Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: SolidStart extracts `server$` blocks into discrete server-only endpoints. Referencing client-side variables (`query()` and `props.userId`) inside `server$` breaks lexical scope because the function executes in a separate process over HTTP RPC. ```typescript import { createSignal } from "solid-js"; import { server$ } from "@solidjs/start/server"; export function UserProfile(props: { userId: string }) { const [query, setQuery] = createSignal(""); // ANTI-PATTERN: Leaks client signal closure into server$ function; // Vinxi bundle extraction strips client context, causing runtime ReferenceError or silent data bug. const searchUsers = server$(async () => { const q = query(); // BROKEN: Signal does not exist on the server RPC execution context return db.users.findMany({ where: { name: { contains: q }, tenantId: props.userId } }); }); return ( <div> <input onInput={(e) => setQuery(e.currentTarget.value)} /> <button onClick={() => searchUsers()}>Search</button> </div> ); } ``` #### Production Standard (Correct) > **Standard**: State is explicitly serialized and passed across the RPC boundary as arguments. The server endpoint validates the untrusted incoming payload with Zod before database execution. ```typescript import { createSignal } from "solid-js"; import { server$ } from "@solidjs/start/server"; import { z } from "zod"; const SearchInputSchema = z.object({ query: z.string().max(100), tenantId: z.string().uuid() }); // GOOD: server$ defined at module scope with explicit serializable parameters and validation const searchUsers = server$(async (input: unknown) => { "use server"; const { query, tenantId } = SearchInputSchema.parse(input); return await db.users.findMany({ where: { name: { contains: query }, tenantId } }); }); export function UserProfile(props: { userId: string }) { const [query, setQuery] = createSignal(""); const handleSearch = async () => { const results = await searchUsers({ query: query(), tenantId: props.userId }); // Handle results... }; return ( <div> <input onInput={(e) => setQuery(e.currentTarget.value)} /> <button onClick={handleSearch}>Search</button> </div> ); } ``` ### Ad-Hoc Async Server Calls vs. cache() and createAsync() Suspense Integration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `onMount` to fetch server data circumvents SolidStart SSR streaming and hydration capabilities, producing Layout Shifts, waterfalls, and hydration mismatches. ```typescript import { createSignal, onMount } from "solid-js"; import { server$ } from "@solidjs/start/server"; const getProduct = server$(async (id: string) => { return db.product.findUnique({ where: { id } }); }); export function ProductView(props: { productId: string }) { const [product, setProduct] = createSignal<any>(null); // ANTI-PATTERN: Client-only lifecycle fetch introduces SSR flash, // waterfall delays, and bypasses Solid's Suspense orchestrator. onMount(async () => { const data = await getProduct(props.productId); setProduct(data); }); return <div>{product() ? product().name : "Loading..."}</div>; } ``` #### Production Standard (Correct) > **Standard**: Wrapping the server call in `cache()` and routing it through `createAsync()` enables isomorphic execution: it streams HTML during SSR, caches requests, deduplicates fetches, and coordinates seamlessly with Solid's fine-grained `Suspense` system. ```typescript import { Suspense, ErrorBoundary } from "solid-js"; import { query, createAsync } from "@solidjs/router"; import { cache } from "@solidjs/start/server"; import { z } from "zod"; const getProduct = query(cache(async (productId: string) => { "use server"; const validId = z.string().cuid().parse(productId); return await db.product.findUnique({ where: { id: validId } }); }, "getProduct"), "product"); export function ProductView(props: { productId: string }) { const product = createAsync(() => getProduct(props.productId)); return ( <ErrorBoundary fallback={(err) => <div>Failed to load: {err.message}</div>}> <Suspense fallback={<div>Loading product details...</div>}> <div>{product()?.name}</div> </Suspense> </ErrorBoundary> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Boundaries

SolidStart 1.0 Server Functions (server$) and Fine-Grained Reactive Boundaries defines an industrial-grade behavioral standard for frontend engineering. SolidStart 1.0 utilizes Vinxi-driven compilation to transform `server$` calls into JSON RPC endpoints, executing purely on the server while client-side signals remain isolated to the client runtime. Engineers must never close over client-side reactive primitives (signals, stores, memo hooks) inside `server$` bodies, nor expose unvalidated inputs across serialized RPC invocations. Furthermore, asynchronous server data transitions must be coordinated with `cache`, `createAsync`, and `Suspense` rather than embedding manual async effects inside component render scopes. 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 in server$ Closures or Calling Async RPCs Inside Untracked Reactive Render Loops 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 in server$ Closures or Calling Async RPCs Inside Untracked Reactive Render Loops	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 treat `server$` boundaries as remote, untrusted RPC endpoints and parse all incoming parameters using strict schema validators (e.g., Zod, Valibot).

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.