Nuxt 4 Nitro Engine Isolation and Shared Directory SSR Hydration Guardrails

Nuxt 4 establishes a strict architectural boundary by moving client application code into the 'app/' directory, isolating Nitro engine handlers in 'server/', and allowing shared isomorphic utilities solely through 'shared/'. Global or module-level variable declarations within Nitro handlers or shared utilities cause critical cross-request memory leaks and data pollution across concurrent SSR requests. This standard mandates strict request-scoped execution contexts, zero cross-boundary imports between 'app/' and 'server/', and deterministic hydration state isolation.

--- description: Nuxt 4 Nitro Engine Isolation and Shared Directory SSR Hydration Guardrails - Nuxt 4 establishes a strict architectural boundary by moving client application code into the 'app/' directory, isolating Nitro engine handlers in 'server/', and allowing shared isomorphic utilities solely through 'shared/'. Global or module-level variable declarations within Nitro handlers or shared utilities cause critical cross-request memory leaks and data pollution across concurrent SSR requests. This standard mandates strict request-scoped execution contexts, zero cross-boundary imports between 'app/' and 'server/', and deterministic hydration state isolation. 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-production-standard" --- # Nuxt 4 Nitro Engine Isolation and Shared Directory SSR Hydration Guardrails > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Leakage and Boundary Violations in Nuxt 4 Nitro and Shared Layers ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 and Nitro v2 architecture. You must enforce strict directory isolation among app/, server/, and shared/. You must prevent cross-request state pollution caused by module-level state in Nitro handlers and ensure SSR state hydration safety. ## Strict Guidelines - Engineers MUST ALWAYS isolate Nuxt 4 client and SSR component code in the 'app/' directory, server handlers in 'server/', and shared isomorphic code in 'shared/'. - Engineers MUST NOT declare mutable top-level module state in 'server/' routes, Nitro middleware, or 'shared/' modules, as module scope is reused across concurrent requests in Node/Worker SSR environments. - Engineers MUST ALWAYS use 'event.context' or request-bound dependency injection containers in Nitro event handlers to store request-scoped data (such as authenticated user, telemetry traces, and DB clients). - Code in 'app/' MUST NEVER directly import files from 'server/', and code in 'server/' MUST NEVER import Vue composables, components, or UI reactive state from 'app/'. - Utilities in 'shared/' MUST be purely isomorphic; they MUST NEVER import Node.js-only builtins ('fs', 'net'), Nitro runtime APIs, or Vue-specific runtime reactivity primitives ('ref', 'reactive', 'computed'). - Components and composables MUST use Nuxt's 'useState()' instead of Vue's native 'ref()' for any state populated on the server and transferred to the client, preventing SSR hydration mismatches. ## Bad vs Good Implementations ### Cross-Request State Pollution in Nitro Server Handler vs Request Context Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring 'currentUser' at the module level in a Nitro handler causes shared memory contamination across concurrent requests in persistent server processes, leaking sensitive user data. ```typescript // server/api/user/profile.ts import { defineEventHandler, getQuery } from 'h3'; // ANTI-PATTERN: Top-level mutable variable persists across concurrent requests in the same Node/Worker process! let currentUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const query = getQuery(event); if (query.userId) { currentUser = await fetchUserFromDatabase(query.userId as string); } // DANGER: If concurrent request arrives without query.userId or awaiting fetch, // it receives the previous user's data, causing catastrophic data leakage. return { user: currentUser }; }); async function fetchUserFromDatabase(id: string) { return { id, role: 'member' }; } ``` #### Production Standard (Correct) > **Standard**: Variables are strictly scoped to the handler execution lifecycle and stored on 'event.context', ensuring complete state isolation between concurrent SSR requests. ```typescript // server/api/user/profile.ts import { defineEventHandler, getQuery, createError } from 'h3'; export default defineEventHandler(async (event) => { const query = getQuery(event); const userId = query.userId as string | undefined; if (!userId) { throw createError({ statusCode: 400, statusMessage: 'Missing required userId parameter', }); } // Requests are strictly isolated; scoped directly inside handler execution const user = await fetchUserFromDatabase(userId); // Stash in event.context if downstream Nitro middleware/plugins require it event.context.user = user; return { user }; }); async function fetchUserFromDatabase(id: string) { return { id, role: 'member' }; } ``` ### Isomorphic Contract in shared/ vs Architectural Boundary Violation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Vue reactivity into 'shared/' breaks non-Vue Nitro contexts, while importing 'h3' into 'shared/' pollutes client bundles. Using a shared module-level 'ref' also leaks state during SSR. ```typescript // shared/utils/auth.ts import { ref } from 'vue'; // ANTI-PATTERN: Vue runtime imported into shared layer import { getCookie } from 'h3'; // ANTI-PATTERN: Nitro/H3 server dependency imported into shared layer export const globalToken = ref<string | null>(null); export function resolveAuth(event?: any) { if (event) { globalToken.value = getCookie(event, 'auth_token') || null; } return globalToken.value; } ``` #### Production Standard (Correct) > **Standard**: 'shared/' contains exclusively framework-agnostic types and pure validation functions without UI reactivity or server engine dependencies, allowing safe isomorphism across 'app/' and 'server/'. ```typescript // shared/types/auth.ts export interface UserSession { id: string; tenantId: string; roles: readonly string[]; } // shared/utils/validation.ts export function isValidSession(session: unknown): session is UserSession { if (!session || typeof session !== 'object') return false; const candidate = session as Record<string, unknown>; return ( typeof candidate.id === 'string' && typeof candidate.tenantId === 'string' && Array.isArray(candidate.roles) ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Engine Isolation and Shared Directory SSR Hydration Guardrails

Nuxt 4 Nitro Engine Isolation and Shared Directory SSR Hydration Guardrails defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 establishes a strict architectural boundary by moving client application code into the 'app/' directory, isolating Nitro engine handlers in 'server/', and allowing shared isomorphic utilities solely through 'shared/'. Global or module-level variable declarations within Nitro handlers or shared utilities cause critical cross-request memory leaks and data pollution across concurrent SSR requests. This standard mandates strict request-scoped execution contexts, zero cross-boundary imports between 'app/' and 'server/', and deterministic hydration state isolation. 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 Leakage and Boundary Violations in Nuxt 4 Nitro and Shared Layers 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 Leakage and Boundary Violations in Nuxt 4 Nitro and Shared Layers	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 Nuxt 4 client and SSR component code in the 'app/' directory, server handlers in 'server/', and shared isomorphic code in 'shared/'.

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.