Nuxt 4 Nitro Engine & Shared Directory State Isolation Standard

--- description: Nuxt 4 Nitro Engine & Shared Directory State Isolation Standard - Enforces strict isolation between the Nitro v2 server engine, universal client code inside the Nuxt 4 app/ directory, and isomorphic contracts in shared/. Guarantees zero cross-request state leakage, eliminates SSR hydration mismatches, and prevents runtime execution boundary contamination. globs: app/**/*.{ts,vue}, server/**/*.{ts,js}, shared/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt4-nitro-engine-shared-dir-state-isolation" --- # Nuxt 4 Nitro Engine & Shared Directory State Isolation Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Contamination via Module-Level Singletons and Illicit Boundary Imports ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 Nitro Server Engine and directory boundary invariants. You must prevent cross-request state pollution, enforce per-request Nitro context isolation, eliminate isomorphic import contamination across app/, server/, and shared/, and ensure SSR hydration integrity. ## Strict Guidelines - Engineers MUST ALWAYS relocate Vue application architecture (components, composables, pages, layouts) into the `app/` directory according to Nuxt 4 structure. - Engineers MUST NEVER declare mutable module-level state (`let session`, `const cache = new Map()`, `const state = ref()`) in Nitro server handlers, plugins, or universal composables. - Engineers MUST ALWAYS store request-scoped metadata exclusively on `event.context` within Nitro routes and middleware. - Engineers MUST ALWAYS use `useState()` inside universal composables within `app/` to ensure request-isolated, devalue-serializable SSR hydration payloads. - Engineers MUST NEVER import Node.js, H3, or Nitro runtime modules into `app/` or `shared/`, and MUST NEVER import browser-bound DOM APIs or Vue component logic into `server/`. - Shared utilities inside `shared/` MUST remain 100% pure, side-effect free, and strictly limited to types, validation schemas, and pure deterministic algorithms. ## Bad vs Good Implementations ### Nitro Route Handler Request-Scoped State vs Module Singleton Leak #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `let currentUser` at module scope persists across the entire Node.js Nitro worker process. The first user's session data leaks to all subsequent unauthenticated or separate concurrent user requests, triggering critical security vulnerabilities and cross-request state pollution. ```typescript // server/api/user/session.ts - CRITICAL BUG: Module-scoped state leaks across concurrent user requests in Node/Nitro worker let currentUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token && !currentUser) { currentUser = await verifyTokenAndGetUser(token); } return { user: currentUser }; }); ``` #### Production Standard (Correct) > **Standard**: Session identity is stored exclusively on `event.context`, ensuring total encapsulation per HTTP request. The context is destroyed upon request completion, eliminating cross-request data leaks and concurrency race conditions. ```typescript // server/api/user/session.ts - SECURE: Scoped strictly to Nitro H3Event context import { z } from 'zod'; import { UserSessionSchema } from '~~/shared/types/user'; declare module 'h3' { interface H3EventContext { user?: z.infer<typeof UserSessionSchema>; } } export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Scoped strictly to the incoming HTTP request life-cycle event.context.user = await verifyTokenAndGetUser(token); return { user: event.context.user }; }); ``` ### Nuxt 4 app/ Composable Hydration State vs Module-Level Ref #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `ref()` outside the composable factory in an SSR environment creates a single persistent reactive instance in the Node.js server memory, causing Client A's profile data to leak into Client B's server-rendered HTML and triggering hydration mismatch errors. ```typescript // app/composables/useProfile.ts - CRITICAL BUG: Module-scoped reactive ref leaks SSR state across visitors import { ref } from 'vue'; const profileData = ref<Record<string, any> | null>(null); export function useProfile() { const setProfile = (data: Record<string, any>) => { profileData.value = data; }; return { profileData, setProfile }; } ``` #### Production Standard (Correct) > **Standard**: `useState` ties the reactive reference to the Nuxt SSR request instance via `useNuxtApp()`. It safely serializes into the Nuxt SSR payload without leaking memory or cross-request data, and flawlessly hydrates on the client. ```typescript // app/composables/useProfile.ts - PRODUCTION: SSR request-isolated hydration using useState import type { UserProfile } from '~~/shared/types/user'; export function useProfile() { // useState is uniquely keyed and serialized per SSR request cycle const profileData = useState<UserProfile | null>('user-profile-key', () => null); const setProfile = (data: UserProfile) => { profileData.value = data; }; return { profileData: readonly(profileData), setProfile }; } ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Engine & Shared Directory State Isolation Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation between the Nitro v2 server engine, universal client code inside the Nuxt 4 app/ directory, and isomorphic contracts in shared/. Guarantees zero cross-request state leakage, eliminates SSR hydration mismatches, and prevents runtime execution boundary contamination. 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 Contamination via Module-Level Singletons and Illicit Boundary Imports 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 Contamination via Module-Level Singletons and Illicit Boundary Imports	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 relocate Vue application architecture (components, composables, pages, layouts) into the `app/` directory according to Nuxt 4 structure.

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.