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

--- description: SolidStart 1.0 Server Functions (server$) & Fine-Grained Reactive Async Boundaries - Enforces strict boundary isolation between SolidJS client-side fine-grained reactivity and SolidStart 1.0 server$ RPC boundaries. Mandates the use of createAsync and cache primitives, guarantees argument serializability across RPC boundaries, and requires explicit Suspense wrapping to prevent hydration tearing and RPC serialization failures. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-rpc-async-boundaries-solidstart-1-0-s-917" --- # SolidStart 1.0 Server Functions (server$) & Fine-Grained Reactive Async Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Invoking Raw server$ RPCs Directly in Reactive Accessors or Passing Non-Serializable Signal Getters Across the Wire ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 Server Functions and Async Boundary safety. You strictly prohibit raw server$ invocations inside fine-grained reactive contexts (such as createMemo, JSX accessors, or untracked effects) and forbid passing reactive signal accessors across RPC boundaries. Every server-side query must be wrapped with cache() and consumed via createAsync(), mutations must leverage createServerAction$ or Solid router actions, inputs to server$ must be validated with runtime schemas, and all async UI dependencies must be enclosed within Suspense and ErrorBoundary components. ## Strict Guidelines - Engineers MUST ALWAYS wrap data-fetching server$ functions inside cache() and consume them using createAsync() to ensure correct fine-grained integration and hydration replay. - Engineers MUST NOT pass signal accessors, functions, or class instances into server$ calls; inputs must evaluate to JSON-serializable primitives or Plain Old JavaScript Objects (POJOs). - Engineers MUST NEVER execute server$ directly within synchronous JSX templates or createMemo blocks without wrapping in createAsync or resolving via SolidStart action primitives. - Engineers MUST ALWAYS validate all arguments passed to server$ on the server side using runtime validation schemas (e.g., Valibot or Zod) to secure against arbitrary HTTP invocation. - Components consuming async server data MUST ALWAYS be bounded by <Suspense> and <ErrorBoundary> to prevent client-server hydration mismatch and unhandled async rejection panics. - Engineers MUST NOT capture client-only reactive state (signals, stores) in closure scopes directly inside server$ function bodies; pass values explicitly as parameters. ## Bad vs Good Implementations ### Server RPC Invocation & Reactive Async Consumption #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing a signal accessor across the server$ RPC wire fails because functions cannot be serialized. Furthermore, orchestrating server fetches in client-side createEffect causes waterfall network requests, breaks SSR serialization, and guarantees hydration mismatches. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start/server"; const fetchUser = server$(async (getId: () => string) => { // FAILS: getId is a client-side accessor function that cannot serialize across the RPC boundary const id = getId(); return await db.user.findUnique({ where: { id } }); }); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); const [data, setData] = createSignal<any>(null); // ANTI-PATTERN: Direct server$ invocation in effect causes client waterfall and hydration mismatch createEffect(async () => { const result = await fetchUser(userId); // Passing signal getter directly setData(result); }); return ( <div> {/* ANTI-PATTERN: Flashing un-suspended state leads to hydration mismatch */} <h1>{data() ? data().name : "Loading..."}</h1> </div> ); } ``` #### Production Standard (Correct) > **Standard**: The RPC receives a serialized primitive extracted from the signal, validates it with Zod on the server, wraps the fetcher in cache(), and integrates into Solid's fine-grained system via createAsync inside Suspense and ErrorBoundary boundaries. ```typescript import { createSignal, Suspense, ErrorBoundary } from "solid-js"; import { cache, createAsync } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; import { z } from "zod"; const UserIdSchema = z.string().min(1); // Correct: Server function validates inputs and is wrapped in cache() for deduplication and SSR const getUser = cache( server$(async (rawId: string) => { "use server"; const id = UserIdSchema.parse(rawId); const user = await db.user.findUnique({ where: { id } }); if (!user) throw new Error("User not found"); return { id: user.id, name: user.name }; }), "getUser" ); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // Correct: createAsync tracks signal changes and resolves promises fine-grained const user = createAsync(() => getUser(userId())); return ( <ErrorBoundary fallback={(err) => <p>Error: {err.message}</p>}> <Suspense fallback={<p>Loading user profile...</p>}> <div> <h1>{user()?.name}</h1> </div> </Suspense> </ErrorBoundary> ); } ```

Architectural Specification & Invariant Rationale

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

SolidStart 1.0 Server Functions (server$) & Fine-Grained Reactive Async Boundaries defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation between SolidJS client-side fine-grained reactivity and SolidStart 1.0 server$ RPC boundaries. Mandates the use of createAsync and cache primitives, guarantees argument serializability across RPC boundaries, and requires explicit Suspense wrapping to prevent hydration tearing and RPC serialization failures. 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: Invoking Raw server$ RPCs Directly in Reactive Accessors or Passing Non-Serializable Signal Getters Across the Wire 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	Invoking Raw server$ RPCs Directly in Reactive Accessors or Passing Non-Serializable Signal Getters Across the Wire	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 data-fetching server$ functions inside cache() and consume them using createAsync() to ensure correct fine-grained integration and hydration replay.

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.