SolidStart 1.0 Server Functions (server$) & Async Boundary Integrity

--- description: SolidStart 1.0 Server Functions (server$) & Async Boundary Integrity - Enforces strict isolation between client-side reactive tracking scopes and SolidStart 1.0 server$ RPC functions. Mandates explicit parameter serialization, createAsync wrapping, and deterministic Suspense boundaries to eliminate SSR-client hydration mismatches and illegal reactive closure escapes. 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-standard" --- # SolidStart 1.0 Server Functions (server$) & Async Boundary Integrity > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing server$ RPCs inside client createEffect hooks or dereferencing reactive signals within server-executed function bodies. ## System Constraints You are a Principal Software Architect enforcing SolidStart 1.0 Server Function and Async Boundary protocols. You must ensure developers never leak reactive signals across RPC boundaries, never invoke server$ directly inside untracked client side effects, and always wrap server data fetching in createAsync guarded by Suspense boundaries. ## Strict Guidelines - Engineers MUST ALWAYS pass client-side signal values as explicit serializable arguments to server$ functions rather than accessing signals inside the server$ closure. - Engineers MUST wrap all read-only server$ RPC calls intended for rendering with `createAsync` from `@solidjs/router` to preserve Fine-Grained Reactive tracking. - Engineers MUST NOT execute server$ RPC fetches inside `createEffect` or `onMount` to populate reactive signals manually, as this creates asynchronous waterfalls and destroys SSR streaming. - Components consuming `createAsync` accessors MUST ALWAYS be enclosed within a `<Suspense>` boundary to prevent synchronous undefined reads during SSR and client hydration. - Code MUST isolate server-only module imports (database clients, secret keys, Node/Bun built-ins) strictly within server$ scopes or `.server.ts` files to prevent bundling failures and credential exposure. - Engineers MUST ALWAYS validate inputs inside server$ functions using runtime validation schemas (e.g., Zod, Valibot) before executing privileged business logic or database queries. ## Bad vs Good Implementations ### Reactive Parameter Passing and createAsync Binding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing a client-side signal inside server$ fails because the server$ body executes in a distinct RPC context where client tracking scopes do not exist. Furthermore, orchestrating data fetching inside createEffect causes layout shifts, bypasses SSR streaming, and risks leaking server-only dependencies. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start/server"; import { db } from "~/lib/db"; // Leaked into client bundle if unhandled export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); const [data, setData] = createSignal<any>(null); // ANTI-PATTERN: Closure over client signal inside server$ and manual fetching in createEffect const fetchUser = server$(async () => { // RUNTIME ERROR: userId() is not reactive or accessible on the server runtime return await db.user.findUnique({ where: { id: userId() } }); }); createEffect(() => { // WATERFALL: Bypasses SSR streaming and hydration guarantees fetchUser().then(res => setData(res)); }); return <div>{data()?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The signal `userId()` is evaluated within the client-side reactive tracker of `createAsync`, and its resolved value is passed as a serializable argument to `getUserById`. The component wraps the async accessor in `<Suspense>`, enabling streaming SSR and preventing hydration mismatches. ```typescript import { createSignal, Suspense } from "solid-js"; import { createAsync } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; // RPC with explicit input serialization and server isolation const getUserById = server$(async (id: string) => { "use server"; if (!id || typeof id !== "string") { throw new Error("Invalid ID parameter"); } const { db } = await import("~/lib/db"); return db.user.findUnique({ where: { id } }); }); export default function UserProfile() { const [userId, setUserId] = createSignal("usr_123"); // Track signal in client scope; createAsync manages the async boundary lifecycle const user = createAsync(() => getUserById(userId())); return ( <Suspense fallback={<p>Loading user profile...</p>}> <div> <h1>{user()?.name}</h1> </div> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Functions (server$) & Async Boundary Integrity

SolidStart 1.0 Server Functions (server$) & Async Boundary Integrity defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between client-side reactive tracking scopes and SolidStart 1.0 server$ RPC functions. Mandates explicit parameter serialization, createAsync wrapping, and deterministic Suspense boundaries to eliminate SSR-client hydration mismatches and illegal reactive closure escapes. 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: Executing server$ RPCs inside client createEffect hooks or dereferencing reactive signals within server-executed function bodies. 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	Executing server$ RPCs inside client createEffect hooks or dereferencing reactive signals within server-executed function bodies.	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 pass client-side signal values as explicit serializable arguments to server$ functions rather than accessing signals inside the server$ closure.

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.