Nuxt 4 Nitro Server Isolation, Shared Layer Contracts, and SSR State Hydration Guardrails

--- description: Nuxt 4 Nitro Server Isolation, Shared Layer Contracts, and SSR State Hydration Guardrails - Enforces strict architectural boundaries across the Nuxt 4 app/ directory, Nitro v2 server engine, and shared/ directory. Eliminates cross-request state pollution, server-side credential leakage in SSR payload hydration, and un-isolated module-level singletons in persistent worker runtimes. globs: app/**/*.{ts,vue}, server/**/*.{ts,js}, shared/**/*.{ts,js}, nuxt.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt4-nitro-shared-ssr-state-guardrails" --- # Nuxt 4 Nitro Server Isolation, Shared Layer Contracts, and SSR State Hydration Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Pollution via Module Singletons and Server Secrets Leaked in SSR Hydration ## System Constraints You are a Principal Software Architect enforcing enterprise-grade Nuxt 4 and Nitro v2 conventions. Enforce the strict physical partition of the app/, server/, and shared/ directories. Eliminate cross-request memory leaks, prevent client exposure of server-side secrets during hydration, and enforce deterministic, context-isolated execution across all runtime targets (Node.js, Cloudflare Workers, Bun). ## Strict Guidelines - Engineers MUST ALWAYS isolate all client-facing UI logic, Vue components, layouts, pages, and client composables inside the 'app/' directory conforming to Nuxt 4 directory topology. - Engineers MUST NEVER declare mutable variables (e.g., 'let userSession', 'const cache = new Map()') at module scope in Nitro event handlers ('server/api/**', 'server/routes/**') or SSR composables, as persistent Node/Edge worker runtimes share module scope across distinct user requests. - Engineers MUST ALWAYS store request-scoped data on 'event.context' inside Nitro server middleware and routes, rather than relying on global stores or ambient singletons. - Code inside 'shared/' MUST ALWAYS be deterministic, side-effect-free, and runtime-agnostic (pure TypeScript interfaces, Zod validation schemas, pure transformation functions). - Engineers MUST NOT import Node.js built-ins ('fs', 'crypto', 'path'), Nitro utilities ('getCookie', 'readBody'), or server-only environmental secrets into 'shared/' or 'app/' code. - Services MUST sanitize data returned by Nitro route handlers to ensure sensitive server fields (passwords, tokens, database IDs, private flags) are not serialized into the SSR '__NUXT_DATA__' hydration payload. - Components NEVER use ref() or reactive() outside setup() or script setup at top-level module scope; SSR-synchronized state MUST ALWAYS use 'useState<T>(key, init)' with a globally unique key. - Code MUST ensure that any state injected into 'useState()' is JSON-serializable and free of non-serializable objects (DOM nodes, class instances with private state, streams, functions) to prevent SSR hydration serialization crashes. ## Bad vs Good Implementations ### Cross-Request State Pollution in Nitro Handler vs Context-Isolated Storage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-scope variables in long-running Nitro workers (Node, Cloudflare Workers, Fastly) persist across invocations. A concurrent or subsequent request from a different user will read or overwrite 'currentUserCache', leading to critical data leakage and authorization breaches. ```typescript // server/api/user-profile.get.ts import { defineEventHandler, getQuery } from 'h3'; // ANTI-PATTERN: Global module-level mutable state leaks across requests in persistent workers let currentUserCache: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const query = getQuery(event); if (query.userId) { // Mutating module-level variable will leak User A's data to User B on concurrent requests currentUserCache = await fetchUserFromDb(String(query.userId)); } return { user: currentUserCache }; }); ``` #### Production Standard (Correct) > **Standard**: The handler eliminates module-level variables completely. State validation and shaping leverage isomorphic schemas from the 'shared/' layer, and any intermediate contextual data is isolated to the immutable-per-request 'event.context'. ```typescript // server/api/user-profile.get.ts import { defineEventHandler, getQuery, createError } from 'h3'; import { UserProfileSchema, type UserProfile } from '~~/shared/types/user'; export default defineEventHandler(async (event): Promise<{ user: UserProfile }> => { const query = getQuery(event); const userId = query.userId ? String(query.userId) : null; if (!userId) { throw createError({ statusCode: 400, statusMessage: 'User ID is required' }); } // Request-scoped retrieval bound to event context or isolated storage const rawUser = await fetchUserFromDb(userId); // Parse and strip private server fields using isomorphic shared schema const user = UserProfileSchema.parse(rawUser); // Cache within request lifetime using event context if needed across internal plugins event.context.user = user; return { user }; }); ``` ### Shared Directory Isolation and SSR Hydration State Safety #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Node-specific packages or server configuration into 'shared/' breaks client compilation and exposes private keys. Declaring a Vue 'ref' at module level inside a composable leaks client state across server-rendered requests. ```typescript // shared/utils/auth.ts // ANTI-PATTERN: Leaking server runtime dependency and un-hydrated singleton into shared layer import { useRuntimeConfig } from '#imports'; import jwt from 'jsonwebtoken'; // Node-native dependency breaks client build! export const verifySessionToken = (token: string) => { const config = useRuntimeConfig(); // Leaks private server secret into client bundle if imported from app/ return jwt.verify(token, config.jwtSecret); }; // app/composables/useSession.ts // ANTI-PATTERN: Client-side ref used across SSR boundary without useState import { ref } from 'vue'; const globalAuthToken = ref<string | null>(null); // Shared across SSR renders in Node runtime export const useSession = () => { return { globalAuthToken }; }; ``` #### Production Standard (Correct) > **Standard**: The 'shared/' code remains pure TypeScript and platform-agnostic, usable in both browser and Nitro. The composable strictly uses Nuxt's 'useState' primitive inside the factory function to ensure that SSR request isolation is preserved and correctly serialized into the hydration payload. ```typescript // shared/schemas/session.ts // GOOD: Pure, universal runtime validation with no ambient secrets or platform APIs import { z } from 'zod'; export const SessionPayloadSchema = z.object({ userId: z.string().uuid(), role: z.enum(['admin', 'member', 'guest']), expiresAt: z.number().int() }); export type SessionPayload = z.infer<typeof SessionPayloadSchema>; // app/composables/useSession.ts // GOOD: Safe SSR state hydration using useState with scoped key import type { SessionPayload } from '~~/shared/schemas/session'; export const useSession = () => { // useState guarantees isolation across SSR requests and synchronizes payload to client const session = useState<SessionPayload | null>('user-session', () => null); const setSession = (payload: SessionPayload) => { session.value = payload; }; const clearSession = () => { session.value = null; }; return { session: readonly(session), setSession, clearSession }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Isolation, Shared Layer Contracts, and SSR State Hydration Guardrails

Nuxt 4 Nitro Server Isolation, Shared Layer Contracts, and SSR State Hydration Guardrails defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural boundaries across the Nuxt 4 app/ directory, Nitro v2 server engine, and shared/ directory. Eliminates cross-request state pollution, server-side credential leakage in SSR payload hydration, and un-isolated module-level singletons in persistent worker runtimes. 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: Cross-Request State Pollution via Module Singletons and Server Secrets Leaked in SSR Hydration 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	Cross-Request State Pollution via Module Singletons and Server Secrets Leaked in SSR Hydration	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 isolate all client-facing UI logic, Vue components, layouts, pages, and client composables inside the 'app/' directory conforming to Nuxt 4 directory topology.

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.