SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Boundaries

--- description: SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Boundaries - Enforces architectural boundaries for SolidStart 1.0 server$ RPCs, requiring createAsync/cache integration within Suspense boundaries. Prevents client signal closure leakage into server boundaries, serialization failures, and hydration mismatches caused by raw server calls in reactive scopes. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-fn-async-boundaries" --- # SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Raw server$ Invocations in Reactive Scopes & Passing Non-Serializable Signal Accessors across RPC Boundaries ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions & Async Boundaries. Mandate that all server$ RPCs strictly adhere to Nitro/Vinxi execution context separation, Seroval serializability invariants, and Solid reactive boundary constraints. Disallow passing reactive signal accessors into server RPCs, executing uncoordinated side-effects in tracking scopes, and bypassing Suspense/createAsync boundaries. ## Strict Guidelines - Engineers MUST ALWAYS wrap read-only server RPC functions with `cache` (or `query`) and consume them via `createAsync` to wire them into Solid's fine-grained Suspense boundaries. - Engineers MUST NOT pass raw Signal accessors (e.g., `userId` without calling `userId()`), DOM nodes, or functions across `server$` function boundaries. - Components NEVER execute raw async `server$` invocations directly in the component execution scope; mutations MUST use `action()` wrapped handlers with `useSubmission`. - Services MUST validate and parse all incoming payload parameters at the `server$` boundary using strict runtime schemas (e.g., Valibot or Zod) to defend against forged client RPC payloads. - Code SHOULD pass explicit, serializable primitive values or pure records to `server$` functions to ensure seamless hydration and Seroval transport. ## Bad vs Good Implementations ### Bypassing createAsync and Passing Reactive Getters to server$ #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing a signal getter (`userId`) to a server function triggers a serialization error because functions cannot cross the network boundary. Additionally, fetching inside a `createEffect` bypasses SolidStart's SSR stream rendering, causes client-side waterfalls, and breaks fine-grained Suspense coordination. ```typescript import { createSignal, createEffect } from "solid-js"; // Bad: Raw server$ without cache/action, leaking client reactive scope const fetchUserData = async (idAccessor: () => string) => { "use server"; // Runtime failure: idAccessor is not serializable across RPC boundary const res = await db.user.findUnique({ where: { id: idAccessor() } }); return res; }; export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); const [data, setData] = createSignal<any>(null); // Bad: Triggering raw async call inside effect breaks Suspense and hydration streaming createEffect(async () => { const user = await fetchUserData(userId); setData(user); }); return <div>{data() ? data().name : "Loading..."}</div>; } ``` #### Production Standard (Correct) > **Standard**: The good implementation uses `cache()` with a unique key, invokes the accessor `userId()` on the client to send a pure serialized string, validates the payload with Valibot inside the `use server` block, and integrates seamlessly with `<Suspense>` via `createAsync`. ```typescript import { createSignal, Suspense, type Component } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import * as v from "valibot"; const UserIdSchema = v.string(); // Good: Cached RPC with parameter validation and serializable primitives const getUser = cache(async (id: string) => { "use server"; const validId = v.parse(UserIdSchema, id); const user = await db.user.findUnique({ where: { id: validId } }); if (!user) throw new Error("User not found"); return { id: user.id, name: user.name }; }, "getUser"); const UserProfile: Component = () => { const [userId, setUserId] = createSignal("usr_123"); // Good: createAsync tracks signal changes and binds directly to Suspense const user = createAsync(() => getUser(userId())); return ( <Suspense fallback={<div>Loading user profile...</div>}> <div>{user()?.name}</div> </Suspense> ); }; export default UserProfile; ```

Architectural Specification & Invariant Rationale

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

SolidStart 1.0 Server Functions (server$) & Fine-Grained Async Boundaries defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural boundaries for SolidStart 1.0 server$ RPCs, requiring createAsync/cache integration within Suspense boundaries. Prevents client signal closure leakage into server boundaries, serialization failures, and hydration mismatches caused by raw server calls in reactive 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: Raw server$ Invocations in Reactive Scopes & Passing Non-Serializable Signal Accessors across RPC 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	Raw server$ Invocations in Reactive Scopes & Passing Non-Serializable Signal Accessors across RPC 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 wrap read-only server RPC functions with `cache` (or `query`) and consume them via `createAsync` to wire them into Solid's fine-grained Suspense boundaries.

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.