Nuxt 4 Nitro Server Engine Boundaries, Shared Directory Purity, and SSR State Isolation

--- description: Nuxt 4 Nitro Server Engine Boundaries, Shared Directory Purity, and SSR State Isolation - Mandate strict runtime and directory isolation across Nuxt 4's app/, server/, and shared/ boundaries. Prevent catastrophic multi-tenant cross-request state pollution in Nitro route handlers and Nuxt SSR composables by eliminating module-level mutable state and restricting shared/ to stateless isomorphic logic. 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-boundary-state-isolation" --- # Nuxt 4 Nitro Server Engine Boundaries, Shared Directory Purity, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Multi-Tenant Data Leaks via Nitro Module-Level Globals and Impure Shared Directory Imports ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architectural constraints, Nitro v2 execution invariants, and SSR state isolation. Enforce strict directory isolation between `app/` (Vue UI application), `server/` (Nitro server engine, API routes, tasks, and middleware), and `shared/` (isomorphic types, pure utils, and validation schemas). Never allow cross-request state leakage through module-scoped mutable variables in server handlers or Vue composables. Reject client-only imports in Nitro and server-only modules in `app/` or `shared/`. ## Strict Guidelines - Engineers MUST ALWAYS isolate request-specific state in Nitro server handlers using `event.context` or local function scope, never at the module root. - Engineers MUST ALWAYS use `useState<T>()` with deterministic unique keys for state shared between SSR and client, ensuring complete isolation per incoming HTTP request. - Engineers MUST NOT declare naked module-level reactive state (`ref()`, `reactive()`, or mutable variables) in composables or server route files. - Engineers MUST NOT import Node.js-only dependencies, Nitro storage, database clients, or server secrets into `app/` or `shared/`. - Engineers MUST NOT import Vue composables, reactivity APIs (`ref`, `computed`), or browser-only APIs (`window`, `localStorage`) into `server/` or `shared/`. - Code in `shared/` MUST be completely isomorphic, stateless, and side-effect-free, limited strictly to data schemas (e.g., Zod), type definitions, and pure algorithmic utilities. - Services in `server/api/` and `server/routes/` MUST wrap all request processing inside `defineEventHandler()` and derive tenant/user context exclusively from `H3Event`. ## Bad vs Good Implementations ### Nitro Server Route State Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables outside the event handler causes cross-request pollution in persistent server environments (Node.js, Bun, Cloudflare Workers). In concurrent traffic, Request B overwrites `currentTenantId` while Request A is awaiting the database query, leaking private tenant data. ```typescript // server/api/profile.ts import { defineEventHandler, getHeader } from 'h3'; import { db } from '../utils/db'; // ANTI-PATTERN: Module-scoped state shared across ALL incoming concurrent requests in Nitro let currentTenantId: string | null = null; export default defineEventHandler(async (event) => { currentTenantId = getHeader(event, 'x-tenant-id') || null; // Race condition: Next request overwrites currentTenantId before db.query resolves const profile = await db.query('SELECT * FROM profiles WHERE tenant_id = ?', [currentTenantId]); return { profile }; }); ``` #### Production Standard (Correct) > **Standard**: Request data is completely scoped to the function execution context and `event.context`, guaranteeing safe concurrent execution without multi-tenant cross-talk or race conditions. ```typescript // server/api/profile.ts import { defineEventHandler, getHeader, createError } from 'h3'; import { db } from '../utils/db'; export default defineEventHandler(async (event) => { // INVARIANT: Request-scoped isolation directly bound to H3Event context const tenantId = getHeader(event, 'x-tenant-id'); if (!tenantId) { throw createError({ statusCode: 400, statusMessage: 'Missing x-tenant-id header' }); } event.context.tenantId = tenantId; const profile = await db.query('SELECT * FROM profiles WHERE tenant_id = ?', [tenantId]); return { profile }; }); ``` ### Nuxt 4 Composables State Hydration vs Module Leak #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: A module-level `ref` instantiated in Node.js memory during SSR is shared across all incoming visitor requests, exposing the first user's session data to subsequent users. ```typescript // app/composables/useSession.ts import { ref } from 'vue'; import type { UserSession } from '~~/shared/types/auth'; // ANTI-PATTERN: Module-level ref persists in the SSR Node.js process across different users const sessionState = ref<UserSession | null>(null); export const useSession = () => { const setSession = (user: UserSession) => { sessionState.value = user; }; return { sessionState, setSession }; }; ``` #### Production Standard (Correct) > **Standard**: `useState` creates a request-isolated, SSR-friendly reactive state that serializes securely into the Nuxt hydration payload and avoids persistent server memory contamination. ```typescript // app/composables/useSession.ts import type { UserSession } from '~~/shared/types/auth'; export const useSession = () => { // INVARIANT: useState binds state uniquely to the current Nuxt SSR request context // and automatically hydrates safely to the browser client const sessionState = useState<UserSession | null>('user-session-state', () => null); const setSession = (user: UserSession) => { sessionState.value = user; }; return { sessionState, setSession }; }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine Boundaries, Shared Directory Purity, and SSR State Isolation

Nuxt 4 Nitro Server Engine Boundaries, Shared Directory Purity, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Mandate strict runtime and directory isolation across Nuxt 4's app/, server/, and shared/ boundaries. Prevent catastrophic multi-tenant cross-request state pollution in Nitro route handlers and Nuxt SSR composables by eliminating module-level mutable state and restricting shared/ to stateless isomorphic logic. 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: Multi-Tenant Data Leaks via Nitro Module-Level Globals and Impure Shared Directory 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	Multi-Tenant Data Leaks via Nitro Module-Level Globals and Impure Shared Directory 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 ALWAYS isolate request-specific state in Nitro server handlers using `event.context` or local function scope, never at the module root.

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.