Nuxt 4 Nitro Engine Isolation and Shared Directory Boundary Enforcement

--- description: Nuxt 4 Nitro Engine Isolation and Shared Directory Boundary Enforcement - Enforces strict boundary separation between Nitro server execution, client hydration, and Nuxt 4's restructured app/ and shared/ directories. Prohibits global module-level mutable state in Nitro handlers to prevent cross-request SSR memory leaks and tenant data contamination. 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/nuxt-4-nitro-shared-directory-state-isolation" --- # Nuxt 4 Nitro Engine Isolation and Shared Directory Boundary Enforcement > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request State Bleed and Illegal Module Imports Across Nitro Server and Client Boundaries ## System Constraints You are a Principal Software Architect enforcing architectural integrity in Nuxt 4 codebases. You must mandate strict directory boundaries following the Nuxt 4 migration (app/, server/, shared/), eradicate module-level mutable state in Nitro handlers to avoid cross-request data leaks during SSR, and guarantee safe isomorphic code sharing via the shared/ directory. ## Strict Guidelines - Engineers MUST ALWAYS isolate SSR state using useState() or per-request event.context in Nitro, NEVER top-level module variables. - Engineers MUST place universal code, pure utility functions, and domain types in the root 'shared/' directory, strictly avoiding environment-specific primitives (window, document, process.server) inside it. - Engineers MUST NOT import server-only packages (such as database drivers, crypto primitives, or secret keys) into 'app/' or 'shared/' directories. - Nitro event handlers MUST declare mutable state exclusively within the defineEventHandler callback scope or attach request-scoped data to 'event.context'. - Hydration state passed from Nitro or SSR MUST be serializable; engineers MUST NOT serialize live class instances, functions, or circular references into Nuxt payload state. - Engineers MUST honor the Nuxt 4 directory structure: client application code lives strictly under 'app/', Nitro server code under 'server/', and isomorphic code under 'shared/'. ## Bad vs Good Implementations ### Nitro Server Handler: Cross-Request State Pollution via Global Scope #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables in Nitro handler module scope creates a shared memory reference across all incoming requests in the persistent Node/Nitro runtime worker, resulting in catastrophic cross-tenant data leakage. ```typescript // server/api/user-session.ts import { defineEventHandler, getQuery } from 'h3'; // CRITICAL FLAW: Global module state shared across concurrent requests let currentUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const query = getQuery(event); if (query.userId) { currentUser = { id: query.userId as string, role: 'member' }; } // Under concurrent traffic, Request B reads Request A's mutated currentUser! return { user: currentUser }; }); ``` #### Production Standard (Correct) > **Standard**: Variables scoped strictly inside defineEventHandler or attached to event.context ensure complete memory isolation between concurrent HTTP requests. ```typescript // server/api/user-session.ts import { defineEventHandler, getQuery, createError } from 'h3'; interface UserSession { id: string; role: string; } export default defineEventHandler((event): { user: UserSession } => { const query = getQuery(event); const userId = query.userId; if (typeof userId !== 'string' || !userId) { throw createError({ statusCode: 400, statusMessage: 'Invalid userId' }); } // SAFE: Bound entirely to the request-specific event context lifecycle const session: UserSession = { id: userId, role: 'member' }; event.context.user = session; return { user: session }; }); ``` ### Nuxt 4 Shared Directory Boundary vs SSR State Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Client composables importing from server/ break build trees and leak server-side secrets or native bindings to the client bundle. Top-level ref() outside useState() bleeds across SSR requests on the server worker. ```typescript // app/composables/useProfile.ts import { ref } from 'vue'; // ANTI-PATTERN: Client composable importing directly from server directory import { fetchUserFromDb } from '../../server/utils/db'; // ANTI-PATTERN: Plain module-level ref leaks state across SSR requests const globalProfile = ref<any>(null); export const useProfile = () => { const load = async (id: string) => { globalProfile.value = await fetchUserFromDb(id); }; return { globalProfile, load }; }; ``` #### Production Standard (Correct) > **Standard**: Shared types reside in 'shared/', decoupled from server logic. useState scopes hydration state per SSR request instance, preventing memory leaks and hydration mismatches. ```typescript // shared/types/profile.ts export interface UserProfile { id: string; displayName: string; } // app/composables/useProfile.ts import type { UserProfile } from '~~/shared/types/profile'; export const useProfile = (userId: string) => { // SAFE: useState scopes SSR reactive state to the current request nuxtApp instance const profile = useState<UserProfile | null>(`profile-${userId}`, () => null); const load = async () => { const { data } = await useFetch<UserProfile>(`/api/users/${userId}`); if (data.value) { profile.value = data.value; } }; return { profile: readonly(profile), load }; }; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Engine Isolation and Shared Directory Boundary Enforcement defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary separation between Nitro server execution, client hydration, and Nuxt 4's restructured app/ and shared/ directories. Prohibits global module-level mutable state in Nitro handlers to prevent cross-request SSR memory leaks and tenant data 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 Bleed and Illegal Module Imports Across Nitro Server and Client Boundaries 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 Bleed and Illegal Module Imports Across Nitro Server and Client Boundaries	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 SSR state using useState() or per-request event.context in Nitro, NEVER top-level module variables.

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.