Nuxt 4 Nitro Server Isolation and Shared Directory Boundary Governance

--- description: Nuxt 4 Nitro Server Isolation and Shared Directory Boundary Governance - Enforces strict boundary contracts across Nuxt 4's app/, server/, and shared/ directories, preventing cross-request state contamination in Nitro server handlers and hydration mismatches during SSR. Eliminates module-scoped mutable state on the server, restricts shared/ to runtime-agnostic isomorphic code, and mandates deterministic, scoped state hydration via useState. 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-engine-and-shared-isolation" --- # Nuxt 4 Nitro Server Isolation and Shared Directory Boundary Governance > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Scoped Mutable State in Nitro Handlers and Cross-Boundary Pollution via Shared Directory ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architectural boundaries and Nitro runtime safety. You must prevent cross-request state leaks, enforce the new Nuxt 4 app/ layout, ensure isomorphic purity in shared/, and eliminate un-isolated SSR state hydration failures. ## Strict Guidelines - Engineers MUST NEVER declare mutable variables (let, var, Set, Map, reactive objects) in Nitro server route module scopes (server/api/*, server/routes/*); all mutable state MUST reside in event.context or an external thread-safe datastore to prevent cross-request data leaks. - Engineers MUST restrict the shared/ directory strictly to pure, isomorphic TypeScript utilities, schema validators (e.g., Zod, Valibot), and type definitions; shared/ MUST NOT import Vue runtime APIs (ref, computed), Nitro server primitives (H3Event, defineEventHandler), or platform-specific globals (window, document, process.env). - Engineers MUST locate all frontend application code (components/, composables/, pages/, layouts/, middleware/) exclusively inside the app/ directory in accordance with the Nuxt 4 specification. - Engineers MUST manage SSR hydration state using Nuxt's useState() with unique, deterministic keys; module-level ref() or reactive() declarations in app/ composables are strictly prohibited as they leak state across requests on the Node.js/Nitro server thread. - Nitro event handlers MUST return immutable or freshly instantiated plain JavaScript objects to avoid in-memory reference sharing across simultaneous client connections. - Nitro middleware and routes MUST access request-specific metadata through getRouterParams(event), getQuery(event), readBody(event), or event.context, and MUST NEVER depend on global execution context or ambient request stores. - Composables executing during SSR MUST NOT invoke client-only lifecycle hooks or access document/window without guard checks (import.meta.client or onMounted). ## Bad vs Good Implementations ### Nitro Server Route State Isolation and Shared Schema Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables (`cachedSessionUser`, `requestCounts`) in Nitro handler module scope causes catastrophic cross-request data leakage in persistent server environments (Node.js/Bun). Subsequent requests from different clients will observe or overwrite previous users' state. ```typescript // server/api/user/profile.post.ts import { UserSchema } from '~/shared/types/user'; // Incorrect alias path // CRITICAL SECURITY BUG: Module-scoped state shared across concurrent incoming HTTP requests! let cachedSessionUser: any = null; const requestCounts = new Map<string, number>(); export default defineEventHandler(async (event) => { const body = await readBody(event); cachedSessionUser = body.user; // Leaks user data to subsequent requests from different users const ip = getRequestIP(event) || 'unknown'; requestCounts.set(ip, (requestCounts.get(ip) || 0) + 1); return { user: cachedSessionUser, totalRequests: requestCounts.get(ip) }; }); ``` #### Production Standard (Correct) > **Standard**: Uses Nuxt 4's `#shared` subpath import with a pure schema validator. State is strictly scoped per request using `readValidatedBody` and Nitro's request-isolated `event.context`, eliminating cross-tenant memory leaks. ```typescript // shared/utils/user.schema.ts import { z } from 'zod'; // Pure isomorphic contract safe for both app/ and server/ export const UserProfileSchema = z.object({ id: z.string().uuid(), email: z.string().email(), name: z.string().min(1) }); export type UserProfile = z.infer<typeof UserProfileSchema>; // server/api/user/profile.post.ts import { UserProfileSchema } from '#shared/utils/user.schema'; export default defineEventHandler(async (event) => { // Request-scoped execution context: zero cross-request contamination const body = await readValidatedBody(event, (data) => UserProfileSchema.parse(data)); // Ephemeral request context binding event.context.user = body; // Return fresh, isolated payload return { success: true, user: body }; }); ``` ### Nuxt 4 SSR State Hydration vs. Server Singleton Anti-Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defining a `ref()` at the module top level inside a composable instantiates a single instance per Node.js process. During SSR, multiple users rendering pages concurrently will mutate and read each other's state. ```typescript // app/composables/useUserProfile.ts import { ref } from 'vue'; // CRITICAL SSR LEAK: Module-level reactive state persists in Nitro server memory! const globalUserProfile = ref<any>(null); export const useUserProfile = () => { const setUser = (user: any) => { globalUserProfile.value = user; }; return { profile: globalUserProfile, setUser }; }; ``` #### Production Standard (Correct) > **Standard**: Leverages `useState()` with a unique key. During SSR, Nuxt creates request-isolated state and automatically serializes it to the client payload (`window.__NUXT__`), preventing server-thread data leaks and avoiding hydration mismatch warnings. ```typescript // app/composables/useUserProfile.ts import type { UserProfile } from '#shared/utils/user.schema'; export const useUserProfile = () => { // Deterministic SSR-safe state hydration unique to each SSR lifecycle and client session const profile = useState<UserProfile | null>('user-profile-state', () => null); const setUser = (user: UserProfile) => { profile.value = user; }; const clearUser = () => { profile.value = null; }; return { profile: readonly(profile), setUser, clearUser }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Isolation and Shared Directory Boundary Governance

Nuxt 4 Nitro Server Isolation and Shared Directory Boundary Governance defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary contracts across Nuxt 4's app/, server/, and shared/ directories, preventing cross-request state contamination in Nitro server handlers and hydration mismatches during SSR. Eliminates module-scoped mutable state on the server, restricts shared/ to runtime-agnostic isomorphic code, and mandates deterministic, scoped state hydration via useState. 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: Module-Scoped Mutable State in Nitro Handlers and Cross-Boundary Pollution via Shared Directory 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	Module-Scoped Mutable State in Nitro Handlers and Cross-Boundary Pollution via Shared Directory	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 NEVER declare mutable variables (let, var, Set, Map, reactive objects) in Nitro server route module scopes (server/api/, server/routes/)

Engineers MUST NEVER declare mutable variables (let, var, Set, Map, reactive objects) in Nitro server route module scopes (server/api/*, server/routes/*); all mutable state MUST reside in event.context or an external thread-safe datastore to prevent cross-request data leaks.

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.