Nuxt 4 Nitro Server Engine Isolation & Shared Directory State Guardrails

--- description: Nuxt 4 Nitro Server Engine Isolation & Shared Directory State Guardrails - Enforces strict boundary separation between Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state pollution in Nitro v2 server engines. Mandates pure, runtime-agnostic code in shared/ and strictly isolates SSR state using request-bound context and useState hydration. 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/nuxt-4-nitro-shared-ssr-state-isolation" --- # Nuxt 4 Nitro Server Engine Isolation & Shared Directory State Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request SSR State Pollution & Boundary Contamination in Nuxt 4 ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 directory architecture and Nitro v2 runtime invariants. Mandate absolute isolation of SSR state, prohibit cross-request pollution via module-level singletons, ensure unidirectional dependencies into shared/, and guarantee request-bound Nitro event handling. ## Strict Guidelines - Engineers MUST ALWAYS encapsulate SSR client/server state using Nuxt's `useState()` composable; module-scope `ref()`, `reactive()`, or plain mutable variables in composables or server handlers are strictly forbidden. - Engineers MUST NOT maintain top-level mutable state or singletons in `server/` routes, middleware, or utilities; all request-scoped state MUST be attached directly to `event.context`. - Code placed in the Nuxt 4 `shared/` directory MUST remain strictly runtime-agnostic, deterministic, and free of Node.js built-ins (`fs`, `net`, `crypto`), Nitro-specific globals, or browser DOM APIs. - Engineers MUST NEVER import code from `server/` into `app/` or `shared/`; dependency resolution must strictly adhere to `app/ -> shared/` and `server/ -> shared/` unidirectional flows. - Nitro server routes MUST use `defineEventHandler` with input validation via `readValidatedBody` or `getValidatedQuery` using schemas exported from `shared/`. - Components NEVER execute direct server-only tasks; all SSR data operations must use `useAsyncData` or `useFetch` with deterministic keys to prevent hydration mismatches. ## Bad vs Good Implementations ### Prevent Cross-Request State Pollution in Nitro Route Handlers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables (`currentUserSession`) at the module root of a Nitro server route creates a persistent singleton across requests in long-running SSR runtimes (Node.js, Bun, Cloudflare Workers), resulting in catastrophic cross-request data leaks between users. ```typescript // server/api/user-session.ts import type { H3Event } from 'h3'; // CRITICAL BUG: Module-scoped state shared across concurrent incoming requests let currentUserSession: { userId?: string; role?: string } = {}; export default defineEventHandler(async (event: H3Event) => { const token = getHeader(event, 'authorization'); if (token) { // Mutating global state in SSR/Nitro causes cross-tenant session leakage currentUserSession = await verifyAndExtractSession(token); } return { session: currentUserSession }; }); async function verifyAndExtractSession(_token: string) { return { userId: '123', role: 'admin' }; } ``` #### Production Standard (Correct) > **Standard**: Session context is stored strictly on `event.context`, ensuring all data is scoped exclusively to the active HTTP request. Types and validation schemas are cleanly imported from `shared/types/auth`. ```typescript // server/api/user-session.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { H3Event } from 'h3'; import { UserSessionSchema, type UserSession } from '~~/shared/types/auth'; declare module 'h3' { interface H3EventContext { session?: UserSession; } } export default defineEventHandler(async (event: H3Event): Promise<{ session: UserSession | null }> => { const token = getHeader(event, 'authorization'); if (!token) { return { session: null }; } // Request-isolated: stored strictly on event.context for the lifetime of this request const session = await verifyAndExtractSession(token); event.context.session = session; return { session: event.context.session }; }); async function verifyAndExtractSession(_token: string): Promise<UserSession> { return UserSessionSchema.parse({ userId: '123', role: 'admin' }); } ``` ### Nuxt 4 Shared Directory Isolation & Safe SSR Composable Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Node.js modules into `shared/` causes client bundle compilation failures or runtime browser crashes. Defining `ref()` at the module top-level outside the composable body leaks reactive state across concurrent SSR renders in the server process. ```typescript // shared/utils/formatters.ts import fs from 'node:fs'; // CRITICAL: Node-specific module bundled into client export const formatConfig = (path: string) => { return fs.readFileSync(path, 'utf-8'); }; // app/composables/useProfile.ts import { ref } from 'vue'; // CRITICAL: Top-level mutable state leaks across concurrent SSR client renders const globalProfile = ref<string | null>(null); export const useProfile = () => { return { profile: globalProfile }; }; ``` #### Production Standard (Correct) > **Standard**: The `shared/` directory contains strictly universal, isomorphic code. The composable leverages `useState()`, which isolates state per SSR request context and serializes data across SSR hydration boundaries without cross-contamination. ```typescript // shared/utils/formatters.ts // Pure, runtime-agnostic schema and pure formatting logic export interface Profile { id: string; displayName: string; } export const sanitizeDisplayName = (name: string): string => { return name.trim().slice(0, 50); }; // app/composables/useProfile.ts import { useState } from '#imports'; import type { Profile } from '~~/shared/utils/formatters'; export const useProfile = () => { // useState guarantees request-isolated, SSR-hydrated reactive state per client session const profile = useState<Profile | null>('user-profile-state', () => null); const setProfile = (newProfile: Profile) => { profile.value = newProfile; }; return { profile: readonly(profile), setProfile }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine Isolation & Shared Directory State Guardrails

Nuxt 4 Nitro Server Engine Isolation & Shared Directory State Guardrails defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary separation between Nuxt 4 app/, server/, and shared/ directories while preventing cross-request state pollution in Nitro v2 server engines. Mandates pure, runtime-agnostic code in shared/ and strictly isolates SSR state using request-bound context and useState hydration. 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 SSR State Pollution & Boundary Contamination in Nuxt 4 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 SSR State Pollution & Boundary Contamination in Nuxt 4	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 encapsulate SSR client/server state using Nuxt's `useState()` composable

Engineers MUST ALWAYS encapsulate SSR client/server state using Nuxt's `useState()` composable; module-scope `ref()`, `reactive()`, or plain mutable variables in composables or server handlers are strictly forbidden.

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.