SolidStart 1.0 Server Functions & Async Boundaries Invariant Standard

--- description: SolidStart 1.0 Server Functions & Async Boundaries Invariant Standard - Enforces strict boundary isolation and reactive lifecycles when using SolidStart server$ RPCs. Mandates that server functions remain pure, isolated compilation units that receive all client parameters via serialized inputs rather than client signal closures, and requires async data consumption to be routed through cache() and createAsync() inside Suspense boundaries to preserve fine-grained reactivity. 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-standard" --- # SolidStart 1.0 Server Functions & Async Boundaries Invariant Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Closing Over Client Signals in server$ Closures or Calling Bare RPCs in Tracking Scopes ## System Constraints You are a Principal Engineer enforcing architectural rigor across SolidStart 1.0 server$ functions and async boundaries. SolidStart extracts server$ closures into independent HTTP RPC routes at compile-time via Vinxi. Engineers MUST NEVER allow server$ scopes to capture client signals or lexical client state. Engineers MUST enforce that server-bound RPCs accept explicit, serializable parameters and that asynchronous data reading is coordinated using createAsync() and cache() wrapped in explicit Suspense boundaries. ## Strict Guidelines - Engineers MUST ALWAYS declare server$ functions with explicit, serializable parameters instead of closing over client-side signals or component-scoped state. - Engineers MUST NOT reference reactive signal getters (e.g., state()) inside the lexical scope of a server$ function body; all reactive values must be passed as arguments at the call site. - Engineers MUST wrap read-only server RPC fetches in cache() from @solidjs/router to enable deduplication, SSR preloading, and invalidation consistency. - Engineers MUST consume server RPC results through createAsync() within UI components rather than invoking bare promises in createEffect or untracked handlers for rendering state. - Components NEVER read asynchronous createAsync accessors without an enclosing <Suspense> boundary in the component tree to avoid hydration mismatches and broken stream boundaries. - Services MUST validate and sanitize all inputs passed to server$ functions using runtime schema validation (e.g., Valibot, Zod) as server functions represent public, unauthenticated HTTP POST endpoints by default. ## Bad vs Good Implementations ### Lexical Signal Closure vs Pure Serialized server$ RPC with createAsync #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: server$ closures are extracted into separate HTTP endpoints by Vinxi during build. Lexically accessing the client-side userId signal causes silent closure corruption or compilation failures. Additionally, orchestrating async data via createEffect and local state breaks SSR streaming, hydration safety, and fine-grained tracking. ```typescript import { createSignal, createEffect } from "solid-js"; import { server$ } from "@solidjs/start/server"; export default function BadUserProfile() { const [userId, setUserId] = createSignal("usr_123"); const [user, setUser] = createSignal<any>(null); // ANTI-PATTERN: Captures client-side signal `userId()` in server$ closure. // This fails at compile-time or leads to runtime RPC extraction crashes. // Also drives state updates through createEffect instead of Suspense/createAsync. const fetchUser = server$(async () => { const id = userId(); // Server boundary violation: lexical closure over client signal return await db.user.findUnique({ where: { id } }); }); createEffect(async () => { const data = await fetchUser(); setUser(data); }); return <div>{user()?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server$ RPC is decoupled from client component state and accepts validated serialized input. createAsync tracks the userId signal reactively on the client, refetching through getUser when the signal updates, while Suspense natively coordinates streaming and SSR. ```typescript import { createSignal, Suspense } from "solid-js"; import { createAsync, cache } from "@solidjs/router"; import { server$ } from "@solidjs/start/server"; import { z } from "zod"; const UserIdSchema = z.string().min(1); // PURE SERVER RPC: Explicit argument signature, cached, and validated const getUser = cache( server$(async (id: string) => { "use server"; const validatedId = UserIdSchema.parse(id); return await db.user.findUnique({ where: { id: validatedId } }); }), "users" ); export default function GoodUserProfile() { const [userId, setUserId] = createSignal("usr_123"); // Passes reactive getter dynamically into cache-wrapped RPC via createAsync const user = createAsync(() => getUser(userId())); return ( <Suspense fallback={<p>Loading user profile...</p>}> <div>{user()?.name}</div> </Suspense> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SolidStart 1.0 Server Functions & Async Boundaries Invariant Standard

SolidStart 1.0 Server Functions & Async Boundaries Invariant Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation and reactive lifecycles when using SolidStart server$ RPCs. Mandates that server functions remain pure, isolated compilation units that receive all client parameters via serialized inputs rather than client signal closures, and requires async data consumption to be routed through cache() and createAsync() inside Suspense boundaries to preserve fine-grained reactivity. 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 Bare RPCs in Tracking Scopes 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 Bare RPCs in Tracking Scopes	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 declare server$ functions with explicit, serializable parameters instead of closing over client-side signals or component-scoped state.

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.