Nuxt 4 Nitro Server Engine & Shared Directory Architectural Isolation Guardrail

--- description: Nuxt 4 Nitro Server Engine & Shared Directory Architectural Isolation Guardrail - Enforces strict boundary separation between Nuxt 4 app/ directory, Nitro server engine, and shared/ utilities. Prevents cross-context contamination, server-side memory leaks from module-scoped mutable state, and SSR hydration mismatches caused by non-serializable or un-isolated runtime references. 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-ssr-isolation" --- # Nuxt 4 Nitro Server Engine & Shared Directory Architectural Isolation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-boundary module imports and global state leakage across concurrent SSR requests in Nuxt 4/Nitro ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 directory structures and Nitro v2 runtime invariants. Mandate strict isolation between app/, server/, and shared/ codebases, ban cross-request mutable state in Nitro handlers, and eliminate client/server hydration vulnerabilities. ## Strict Guidelines - Engineers MUST ALWAYS isolate universal code inside the top-level shared/ directory, ensuring exports are pure, side-effect free, and transport-serializable. - Engineers MUST NOT import server-only code (e.g., node builtins, database clients, Nitro event handlers) into the app/ directory or client components. - Engineers MUST NEVER declare mutable variables (e.g., let cache = {}, new Map()) at the Nitro server module scope, as they leak state across concurrent user requests in Node/Bun runtimes. - Services MUST leverage unctx/h3 event context (`event.context`) or scoped storage per request rather than global state singletons in Nitro server routes. - Components NEVER initialize client-only state globally during setup without wrapping it in useState() or callOnlyIfClient guards to prevent hydration mismatches. ## Bad vs Good Implementations ### Preventing Shared Mutable State in Nitro Event Handlers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable state at the Nitro handler module top-level creates a catastrophic memory leak and security vulnerability where concurrent requests overwrite or leak user session state across threads/evaluations. ```typescript // server/api/user.ts import { defineEventHandler, getQuery } from 'h3'; // ANTI-PATTERN: Module-scoped state shared across concurrent incoming requests let currentUserSession: Record<string, unknown> = {}; export default defineEventHandler(async (event) => { const query = getQuery(event); currentUserSession = { id: query.id, timestamp: Date.now() }; return { user: currentUserSession }; }); ``` #### Production Standard (Correct) > **Standard**: Encapsulates state within the event execution context, leveraging shared types from the universal shared/ directory while maintaining complete request isolation. ```typescript // server/api/user.ts import { defineEventHandler, getQuery, createError } from 'h3'; import type { UserSession } from '~~/shared/types/user'; export default defineEventHandler(async (event): Promise<{ user: UserSession }> => { const query = getQuery(event); if (!query.id || typeof query.id !== 'string') { throw createError({ statusCode: 400, statusMessage: 'Invalid user ID' }); } // SAFE: Scoped to the individual request execution lifecycle const session: UserSession = { id: query.id, timestamp: Date.now(), }; event.context.userSession = session; return { user: session }; }); ``` ### Universal Shared Logic vs Nuxt 4 app/ SSR Hydration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Referencing DOM/window in shared/ crashes Nitro during SSR. Module-scoped ref() creates a single shared reactive reference across all server requests, contaminating hydration and multi-tenant data. ```typescript // shared/utils/formatter.ts // ANTI-PATTERN: Direct browser API access in shared directory breaks SSR export function formatTimestamp(date: Date): string { return `${date.toLocaleDateString()} - Resolution: ${window.innerWidth}px`; } // app/composables/useData.ts // ANTI-PATTERN: Vue ref initialized outside component scope causes SSR state cross-talk import { ref } from 'vue'; const globalState = ref<string>(''); export const useData = () => globalState; ``` #### Production Standard (Correct) > **Standard**: Pure functions in shared/ ensure deterministic client/server parity, while Nuxt's useState ensures hydration state is serialized safely into the HTML payload without leaking between requests. ```typescript // shared/utils/formatter.ts // SAFE: Pure functional utility without runtime-specific globals export function formatTimestamp(date: Date, locale = 'en-US'): string { return new Intl.DateTimeFormat(locale, { dateStyle: 'short', timeStyle: 'short' }).format(date); } // app/composables/useData.ts // SAFE: Nuxt useState manages SSR-safe hydration and per-request scope export const useData = () => { return useState<string>('data-key', () => ''); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine & Shared Directory Architectural Isolation Guardrail

Nuxt 4 Nitro Server Engine & Shared Directory Architectural Isolation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary separation between Nuxt 4 app/ directory, Nitro server engine, and shared/ utilities. Prevents cross-context contamination, server-side memory leaks from module-scoped mutable state, and SSR hydration mismatches caused by non-serializable or un-isolated runtime references. 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-boundary module imports and global state leakage across concurrent SSR requests in Nuxt 4/Nitro 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-boundary module imports and global state leakage across concurrent SSR requests in Nuxt 4/Nitro	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 universal code inside the top-level shared/ directory, ensuring exports are pure, side-effect free, and transport-serializable.

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.