Enforcing SolidStart 1.0 server$ RPC Isolation and createAsync Boundaries

--- description: Enforcing SolidStart 1.0 server$ RPC Isolation and createAsync Boundaries - SolidStart server functions (`server$`) create isolated RPC endpoints that execute strictly on the server and must not capture client-side reactive scope closures. Reactive client signals consumed by server functions must be explicitly passed as serialized arguments, and all resulting async promises must resolve through `createAsync` or action utilities within `<Suspense>` boundaries to preserve fine-grained reactivity and prevent hydration mismatches. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/solidstart-server-rpc-async-boundary-standard" --- # Enforcing SolidStart 1.0 server$ RPC Isolation and createAsync Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Capturing Client Signals in server$ Closures or Calling server$ Unwrapped in Reactive Tracking Scopes ## System Constraints You are a Principal Engineer enforcing SolidStart 1.0 Server Functions & Async Boundaries. Mandate strict isolation between client reactive signal scopes and server-side RPC functions. Enforce pure argument passing to `server$`, mandatory consumption of server data via `createAsync` or `cache` wrapped handlers, and full encapsulation within `<Suspense>` boundaries. Prevent reactive tracking leaks, closure serialization bugs, and untracked network waterfalls across SSR/client transitions. ## Strict Guidelines - Engineers MUST ALWAYS pass client-side signal values as explicit, serializable parameters into `server$` functions rather than referencing client variables directly in the server closure. - Engineers MUST wrap all async data queries powered by `server$` in `createAsync()` from `@solidjs/router` to properly register promises with Solid's Suspense and SSR streaming lifecycle. - Engineers MUST NOT invoke `server$` functions directly inside `createEffect`, `createMemo`, or inline JSX templates without wrapping them in `action()`, `createAsync()`, or transition handlers. - Code SHOULD pair queries with cached access via `cache(async (...) => server$(...), 'cache-key')` to allow deduplicated fetching during SSR and client navigation. - Services MUST ensure return values from `server$` are strictly serializable JSON primitives (no functions, Symbol, circular structures, or unhandled Error instances). - Components NEVER trigger mutations via raw `server$` calls; mutations MUST use `action(async (...) => server$(...))` or `createAction` to ensure cache revalidation hooks trigger reliably. ## Bad vs Good Implementations ### Data Fetching with server$ and createAsync Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Referencing the client signal `userId()` within the `server$` body attempts to serialize a reactive tracking context over the network boundary, which fails at runtime. Calling raw RPCs inside `createEffect` bypasses SolidStart SSR streaming and `<Suspense>` coordination, causing layout thrashing and client-side waterfalls. ```typescript import { createSignal, createEffect } from 'solid-js'; import { server$ } from '@solidjs/start/server'; export default function UserProfile() { const [userId, setUserId] = createSignal('usr_123'); const [user, setUser] = createSignal<any>(null); // BAD: Accessing reactive signal inside server$ closure, triggering side effects via createEffect const fetchUser = server$(async () => { // userId() reference breaks: client signal does not exist in server execution context return await db.users.findUnique({ where: { id: userId() } }); }); createEffect(() => { fetchUser().then((data) => setUser(data)); }); return <div>{user()?.name}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server function accepts `userId` as an explicit serializable parameter. Reactive reactivity is tracked on the client via `createAsync(() => getUser(userId()))`. The call integrates with `cache()` and `<Suspense>`, providing automatic SSR streaming and safe client-side refetching. ```typescript import { createSignal, Suspense } from 'solid-js'; import { createAsync, cache } from '@solidjs/router'; import { server$ } from '@solidjs/start/server'; // GOOD: server$ receives explicit serializable arguments; query is wrapped in cache() const getUser = cache(async (id: string) => { 'use server'; return server$(async (userId: string) => { return await db.users.findUnique({ where: { id: userId } }); })(id); }, 'users.getById'); export default function UserProfile() { const [userId, setUserId] = createSignal('usr_123'); // GOOD: Signal getter passed into createAsync tracks reactive dependencies cleanly const user = createAsync(() => getUser(userId())); return ( <Suspense fallback={<p>Loading user profile...</p>}> <div>{user()?.name}</div> </Suspense> ); } ``` ### Server Mutation Using action() for Cache Invalidation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking a bare `server$` function for state mutations bypasses SolidStart's action pipeline, preventing automated router cache revalidation and leaving client data out of sync. ```typescript import { createSignal } from 'solid-js'; import { server$ } from '@solidjs/start/server'; const updateBio = server$(async (bio: string) => { return await db.user.updateBio(bio); }); export function EditProfile() { const [bio, setBio] = createSignal(''); const handleSubmit = async (e: Event) => { e.preventDefault(); // BAD: Unmanaged server mutation leaves router cache stale await updateBio(bio()); }; return ( <form onSubmit={handleSubmit}> <input value={bio()} onInput={(e) => setBio(e.currentTarget.value)} /> <button type="submit">Save</button> </form> ); } ``` #### Production Standard (Correct) > **Standard**: Encapsulating the mutation in `action()` automatically ties into progressive enhancement, handles submission state, and executes `revalidate()` to synchronize all active `cache()` subscribers across the app. ```typescript import { action, revalidate } from '@solidjs/router'; import { server$ } from '@solidjs/start/server'; const updateBioAction = action(async (formData: FormData) => { 'use server'; const bio = formData.get('bio') as string; await server$(async (newBio: string) => { return await db.user.updateBio(newBio); })(bio); return revalidate('users.getById'); }, 'update-bio'); export function EditProfile() { return ( <form action={updateBioAction} method="post"> <input name="bio" type="text" /> <button type="submit">Save</button> </form> ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Enforcing SolidStart 1.0 server$ RPC Isolation and createAsync Boundaries

Enforcing SolidStart 1.0 server$ RPC Isolation and createAsync Boundaries defines an industrial-grade behavioral standard for frontend engineering. SolidStart server functions (`server$`) create isolated RPC endpoints that execute strictly on the server and must not capture client-side reactive scope closures. Reactive client signals consumed by server functions must be explicitly passed as serialized arguments, and all resulting async promises must resolve through `createAsync` or action utilities within `<Suspense>` boundaries to preserve fine-grained reactivity and prevent hydration mismatches. 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: Capturing Client Signals in server$ Closures or Calling server$ Unwrapped in Reactive 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	Capturing Client Signals in server$ Closures or Calling server$ Unwrapped in Reactive 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 pass client-side signal values as explicit, serializable parameters into `server$` functions rather than referencing client variables directly in 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.