Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcement

--- description: Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcement - Enforces strict boundary isolation between Nuxt 4's app/ directory, Nitro server runtime, and isomorphic shared/ directory. Prevents catastrophic cross-request state pollution in Nitro handlers and ensures client/server hydration parity without runtime capability leaks. 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-state-isolation" --- # Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State in Nitro Handlers and Client/Server Leaks in the Shared Directory ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 directory conventions, Nitro v2 execution integrity, and SSR state isolation. You must reject cross-request state pollution, inappropriate boundary crossings into the shared/ directory, and hydration mismatches caused by un-isolated state initialization. ## Strict Guidelines - Engineers MUST NOT declare mutable module-scoped variables in Nitro server routes, middleware, or plugins (`server/**`), as Node/Bun/Deno runtimes persist module state across concurrent incoming requests. - Engineers MUST isolate request-specific data exclusively using H3 event utilities (`event.context`, `getRouterParams`, `readBody`) or Nitro's native unctx/AsyncLocalStorage primitives. - Engineers MUST strictly preserve the isomorphic purity of the `shared/` directory; code in `shared/` MUST NOT import from `#app`, `vue`, `h3`, or server-only packages. - Engineers MUST organize all Vue frontend code (pages, components, composables, layouts, assets) under the Nuxt 4 `app/` directory root, keeping it distinct from `server/` and `shared/`. - Engineers MUST NEVER use `ref()`, `reactive()`, or plain JavaScript objects at the top-level of SSR composables without wrapping them in Nuxt's `useState()` key-scoped hydration primitive. - Server route handlers MUST return validated typed DTOs defined in `shared/types/` rather than returning raw database or ORM entities to prevent leaking sensitive fields across SSR boundaries. ## Bad vs Good Implementations ### Preventing Nitro Cross-Request State Pollution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable state (`sessionUser`) at module scope in a Nitro route handler causes Cross-Request State Pollution. Because the module stays loaded in memory, concurrent requests will overwrite and leak sensitive user data across disparate tenants. ```typescript // server/api/profile.get.ts import { defineEventHandler } from 'h3'; // CRITICAL SECURITY FLAW: Module-scoped variable shared across ALL requests let sessionUser: { id: string; email: string } | null = null; export default defineEventHandler(async (event) => { const token = event.node.req.headers.authorization; if (token) { sessionUser = await fetchUserFromDb(token); } // Under concurrent traffic, Request A's data leaks into Request B's response return { user: sessionUser }; }); async function fetchUserFromDb(token: string) { return { id: '123', email: '[email protected]' }; } ``` #### Production Standard (Correct) > **Standard**: Variables are strictly scoped to the handler invocation, and intermediate context is attached to the request-specific `event.context`. The returned object is explicitly typed with a shared DTO contract. ```typescript // server/api/profile.get.ts import { defineEventHandler, createError, getHeader } from 'h3'; import type { UserProfileDTO } from '~~/shared/types/user'; export default defineEventHandler(async (event): Promise<UserProfileDTO> => { const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized access: Missing authorization token' }); } // Request-scoped: safe from cross-contamination const user = await fetchUserFromDb(authHeader); // Store in event.context if downstream Nitro middleware or hooks need access event.context.user = user; return { id: user.id, email: user.email }; }); async function fetchUserFromDb(token: string): Promise<UserProfileDTO> { return { id: '123', email: '[email protected]' }; } ``` ### Nuxt 4 Shared Directory Purity vs. Runtime Leakage #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing environment-specific runtime libraries (`vue` or `h3`) into the `shared/` folder breaks isomorphic compilation. It leads to bundle bloat, runtime exceptions in Nitro, or hydration desynchronization in the browser. ```typescript // shared/utils/formatters.ts // ANTI-PATTERN: Leaking Vue client runtime and H3 server runtime into shared directory import { ref } from 'vue'; import { getRequestHeader } from 'h3'; export const globalLocale = ref('en-US'); export function resolveSharedCurrency(amount: number, event?: any) { const clientLocale = globalLocale.value; const headerLocale = event ? getRequestHeader(event, 'accept-language') : null; return new Intl.NumberFormat(headerLocale || clientLocale).format(amount); } ``` #### Production Standard (Correct) > **Standard**: The utility in `shared/` is purely functional and deterministic. Framework-specific state (Vue `useState` or Nitro `event.context`) is resolved outside and passed in explicitly as plain parameters. ```typescript // shared/utils/formatters.ts // PURE ISOMORPHIC STANDARD: Zero external framework/runtime dependencies export interface FormatCurrencyOptions { amount: number; locale: string; currency?: string; } export function formatCurrency({ amount, locale, currency = 'USD' }: FormatCurrencyOptions): string { return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(amount); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcement

Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation between Nuxt 4's app/ directory, Nitro server runtime, and isomorphic shared/ directory. Prevents catastrophic cross-request state pollution in Nitro handlers and ensures client/server hydration parity without runtime capability leaks. 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: Global Module-Level State in Nitro Handlers and Client/Server Leaks in the 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	Global Module-Level State in Nitro Handlers and Client/Server Leaks in the 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 NOT declare mutable module-scoped variables in Nitro server routes, middleware, or plugins (`server/**`), as Node/Bun/Deno runtimes persist module state across concurrent incoming requests.

Engineers MUST NOT declare mutable module-scoped variables in Nitro server routes, middleware, or plugins (`server/**`), as Node/Bun/Deno runtimes persist module state across concurrent incoming requests.

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.