Nuxt 4 Directory Boundaries and Nitro Cross-Request State Isolation

--- description: Nuxt 4 Directory Boundaries and Nitro Cross-Request State Isolation - Enforces architectural boundaries between Nuxt 4 app/, server/, and shared/ directories to eliminate cross-request memory contamination and hydration mismatches. Mandates pure runtime-agnostic code in shared/ and strictly isolates per-request state in Nitro handlers using H3 event context. 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-isolation" --- # Nuxt 4 Directory Boundaries and Nitro Cross-Request State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Contamination via Module-Level Nitro State and Invalid Shared Imports ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architectural patterns, Nitro v2 server engine rules, and strict SSR hydration isolation. Your task is to detect and prevent cross-request state contamination, illegal cross-boundary imports between app/ and server/, and runtime-polluting logic inside shared/. ## Strict Guidelines - Engineers MUST NEVER declare mutable module-level state (e.g., global `let`, `Map`, or singleton instances) in Nitro handlers, middleware, or utilities; state must be scoped to `event.context`. - Engineers MUST isolate shared code within `<rootDir>/shared/` to pure, runtime-agnostic utilities and types, never importing Node.js native APIs, Nitro runtime constructs, or Vue reactivity primitives (`ref`, `reactive`, `computed`). - Engineers MUST NEVER import directly from `server/` into `app/`, or from `app/` into `server/`; all cross-environment primitives must be imported from `shared/`. - Engineers MUST strictly utilize Nuxt 4's `app/` folder convention for frontend-specific code (`app/components/`, `app/composables/`, `app/plugins/`, `app/middleware/`) to prevent build-time directory collisions. - Engineers MUST preserve SSR-to-client hydration integrity by using `useState` for shared Vue reactive state rather than global module variables or bare `ref()` outside the Nuxt setup scope. ## Bad vs Good Implementations ### Nitro Server Handler State Isolation & Shared Directory Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables (`cachedSession`) at the module level in a Nitro handler leaks sensitive user data across concurrent SSR requests. Importing Vue reactive primitives (`ref`) into `shared/` contaminates pure shared logic with client/SSR Vue runtime dependencies. ```typescript // shared/types/user.ts import { ref } from 'vue'; // VIOLATION: Vue reactivity inside shared code export const activeUserCount = ref(0); // server/api/user.post.ts import { activeUserCount } from '~~/shared/types/user'; // VIOLATION: Mutable module-level state causes cross-request contamination in long-running Node/Workers let cachedSession: { userId: string } | null = null; export default defineEventHandler(async (event) => { const body = await readBody(event); cachedSession = { userId: body.userId }; // Memory leak: Leaks to all concurrent requests activeUserCount.value += 1; return { session: cachedSession }; }); ``` #### Production Standard (Correct) > **Standard**: Shared logic is kept strictly runtime-agnostic using pure TypeScript interfaces and guards. Session data is scoped to the Nitro `event.context`, ensuring strict isolation between concurrent requests without memory leaks. ```typescript // shared/utils/validation.ts // Pure, runtime-agnostic schema shared across server and app export interface UserSessionPayload { userId: string; role: 'admin' | 'user'; } export const isValidSessionPayload = (data: unknown): data is UserSessionPayload => { return typeof data === 'object' && data !== null && 'userId' in data && 'role' in data; }; // server/api/user.post.ts import { isValidSessionPayload } from '#shared/utils/validation'; declare module 'h3' { interface H3EventContext { session?: UserSessionPayload; } } export default defineEventHandler(async (event) => { const body = await readBody(event); if (!isValidSessionPayload(body)) { throw createError({ statusCode: 400, statusMessage: 'Invalid payload' }); } // Strictly bound to current request context - no leak across concurrent invocations event.context.session = body; return { session: event.context.session }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Boundaries and Nitro Cross-Request State Isolation

Nuxt 4 Directory Boundaries and Nitro Cross-Request State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural boundaries between Nuxt 4 app/, server/, and shared/ directories to eliminate cross-request memory contamination and hydration mismatches. Mandates pure runtime-agnostic code in shared/ and strictly isolates per-request state in Nitro handlers using H3 event context. 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 Nitro State and Invalid Shared 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 Nitro State and Invalid Shared 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 NEVER declare mutable module-level state (e.g., global `let`, `Map`, or singleton instances) in Nitro handlers, middleware, or utilities

Engineers MUST NEVER declare mutable module-level state (e.g., global `let`, `Map`, or singleton instances) in Nitro handlers, middleware, or utilities; state must be scoped to `event.context`.

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.