Nuxt 4 Directory Restructuring, Nitro Handlers, and SSR State Isolation

--- description: Nuxt 4 Directory Restructuring, Nitro Handlers, and SSR State Isolation - Enforces strict boundary isolation across the Nuxt 4 app/ directory, Nitro server runtime, and shared/ isomorphic module layer. Precludes cross-request state pollution, improper hydration mismatches, and the leak of server secrets into client bundles through rigorous stateless handler construction and pure shared utilities. globs: app/**/*.{ts,vue}, server/**/*.{ts,js}, shared/**/*.{ts,js}, nuxt.config.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt4-nitro-shared-ssr-state-isolation-nuxt-4-nitro-ser-617" --- # Nuxt 4 Directory Restructuring, Nitro Handlers, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Mutable State Leaks Across Nitro Requests and Client Hydration Mismatches via Contaminated Shared Modules ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architecture and Nitro v2 state isolation. You must enforce strict architectural segregation between the app/ directory, root-level server/ engine, and stateless shared/ directory. Flag and eliminate any global mutable singletons, cross-request memory leaks in Nitro handlers, client-side imports in server contexts, and un-isolated SSR state hydration bugs. ## Strict Guidelines - Engineers MUST ALWAYS isolate all Vue-layer application code inside the app/ directory (components, composables, pages, layouts, middleware) when running under Nuxt 4 compatibilityMode. - Engineers MUST NOT declare mutable module-level state, global singletons, or top-level shared variables in server/ handlers or shared/ modules that persist across incoming requests. - Engineers MUST ALWAYS scope request-specific metadata, authenticated identity, and transactional databases to Nitro's event.context within defineEventHandler. - Engineers MUST ALWAYS use useState() inside the app/ composables layer for SSR-safe state hydration, NEVER using native Vue reactive() or ref() at module scope. - Shared utilities inside shared/ MUST remain purely functional, deterministic, and free of platform-specific imports (e.g., node:* builtins, useFetch, window, or document). - Nitro server routes MUST NOT import code from app/, ensuring complete build-time separation between client bundles and Nitro execution contexts. - Engineers MUST validate all request payloads and queries in Nitro routes using type-safe schemas (e.g., v.parse or z.parse) via readValidatedBody and getValidatedQuery. ## Bad vs Good Implementations ### Nitro Request State Pollution vs Request-Scoped Event Context #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-level variables in Nitro server routes persist across concurrent invocations in Node and Worker runtimes, leaking confidential cross-tenant state between unrelated incoming requests. ```typescript // server/api/profile.ts import { defineEventHandler } from 'h3'; // CRITICAL BUG: Module-scoped state shared across ALL concurrent requests/tenants in Nitro! let activeUserSession: { userId: string; tenantId: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token) { activeUserSession = await verifySession(token); } // Cross-request pollution: Request B can read Request A's tenant session return { tenantId: activeUserSession?.tenantId }; }); ``` #### Production Standard (Correct) > **Standard**: Attaching request-specific state to event.context guarantees complete isolation between incoming requests and prevents cross-tenant data leaks during high-concurrency SSR. ```typescript // server/api/profile.ts import { defineEventHandler, createError, getHeader } from 'h3'; import { verifySession } from '../utils/auth'; declare module 'h3' { interface H3EventContext { session?: { userId: string; tenantId: string }; } } export default defineEventHandler(async (event) => { const authHeader = getHeader(event, 'authorization'); if (!authHeader) { throw createError({ statusCode: 401, message: 'Missing Authorization Header' }); } // State is explicitly scoped to the single H3 event execution context const session = await verifySession(authHeader); event.context.session = session; return { tenantId: event.context.session.tenantId }; }); ``` ### Nuxt 4 Shared Directory and SSR Composable Hydration Safety #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Vue reactive primitives into shared/ contaminates the shared layer, creates persistent module singletons in SSR, and causes memory leaks and unpredictable hydration desynchronization. ```typescript // shared/utils/user.ts import { ref } from 'vue'; // ILLEGAL: Vue reactive dependency in isomorphic shared/ // Module-scope state leaks in SSR and breaks server-side multi-threading export const cachedUserPreferences = ref<Record<string, unknown>>({}); export function calculateDiscount(total: number): number { return total * 0.9; // Undocumented client/server shared logic with side-effects } ``` #### Production Standard (Correct) > **Standard**: The shared utility remains pure, stateless, and free of client/server framework bindings. The reactive state resides strictly in app/composables using useState for serialized hydration. ```typescript // shared/utils/pricing.ts // PURE ISOMORPHIC UTILITY: Zero dependencies, deterministic, zero side-effects export interface DiscountRules { rate: number; minimumSpend: number; } export function calculateDiscount(total: number, rules: DiscountRules): number { if (total < rules.minimumSpend) return total; return total - (total * rules.rate); } // app/composables/useUserPreferences.ts // SSR-Safe hydration state correctly isolated in app/ directory export const useUserPreferences = () => { return useState<Record<string, unknown>>('user_preferences', () => ({})); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Directory Restructuring, Nitro Handlers, and SSR State Isolation

Nuxt 4 Directory Restructuring, Nitro Handlers, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation across the Nuxt 4 app/ directory, Nitro server runtime, and shared/ isomorphic module layer. Precludes cross-request state pollution, improper hydration mismatches, and the leak of server secrets into client bundles through rigorous stateless handler construction and pure shared utilities. 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 Mutable State Leaks Across Nitro Requests and Client Hydration Mismatches via Contaminated Shared Modules 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 Mutable State Leaks Across Nitro Requests and Client Hydration Mismatches via Contaminated Shared Modules	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 isolate all Vue-layer application code inside the app/ directory (components, composables, pages, layouts, middleware) when running under Nuxt 4 compatibilityMode.

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.