Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcements

--- description: Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcements - Enforces strict architecture and runtime boundaries between Nuxt 4's app/ directory, Nitro server/ runtime, and the polymorphic shared/ directory. Prohibits module-scoped mutable state, cross-boundary runtime imports, and non-isolated server-side hydration traps that cause cross-request state pollution in production SSR. 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-state-boundary" --- # Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcements > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Scoped Mutable Singletons and Cross-Boundary Runtime Leaks across Nuxt 4 app/, server/, and shared/ Directories ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 and Nitro v2 production architectural boundaries. In Nuxt 4, client and Vue rendering code lives exclusively in `app/`, Nitro server endpoints and middleware live in `server/`, and isomorphic schemas, contracts, and pure functions live in `shared/`. You must strictly prevent cross-request state pollution, runtime leakage between Nitro and Vue, and non-serializable hydration mismatches. ## Strict Guidelines - Engineers MUST ALWAYS isolate state to the request lifecycle using Nuxt `useState()` in `app/` or `event.context` in `server/`; module-level mutable variables (`let`, `new Map()`, `ref()`) at file scope are strictly forbidden. - Engineers MUST NOT import Nitro server packages (e.g., `h3`, `nitropack`, `#imports` from server) inside `app/` or `shared/` directories. - Engineers MUST NOT import Vue runtime APIs (`ref`, `reactive`, `computed`, `inject`, lifecycle hooks) into `server/` routes or the isomorphic `shared/` directory. - Code placed in the `shared/` directory MUST remain strictly isomorphic, pure, and side-effect-free (e.g., Zod schemas, TypeScript types, pure calculation functions without environment-specific global dependencies). - Nitro server routes (`server/api/**`, `server/routes/**`) MUST return plain JSON-serializable payloads; returning raw Node.js streams, circular objects, or symbols without proper serialization adapters is prohibited. - Client data fetching in `app/` MUST ALWAYS wrap server calls in `useAsyncData` or `useFetch` with unique deterministic keys to prevent hydration payload desynchronization during SSR. - Engineers MUST ALWAYS verify that secrets and server credentials in `nuxt.config.ts` reside under `runtimeConfig` and NEVER under `runtimeConfig.public`. ## Bad vs Good Implementations ### Preventing Cross-Request State Pollution in Nitro API Routes #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Module-level variables in Nitro v2 event handlers persist across requests in long-lived Node.js, Bun, or edge worker processes. This causes critical cross-request data leaks where User B accesses User A's cached state. ```typescript // server/api/profile.ts - CRITICAL BUG: Module-scoped state leaks across requests in Nitro let currentUserCache: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token && !currentUserCache) { // Concurrently executing requests will share and overwrite this instance currentUserCache = await verifyAndFetchUser(token); } return { user: currentUserCache }; }); ``` #### Production Standard (Correct) > **Standard**: State is bound exclusively to the H3 `event.context` object, guaranteeing total isolation between concurrent requests without risking multi-tenant data leaks. ```typescript // server/api/profile.ts - PRODUCTION-GRADE: Scoped to request event.context export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Request-scoped storage via event context if (!event.context.user) { event.context.user = await verifyAndFetchUser(token); } return { user: event.context.user }; }); ``` ### Enforcing Isomorphic Pure Boundaries in the Nuxt 4 shared/ Directory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Vue reactivity or H3 server helpers into `shared/` pollutes the polymorphic contract. Client bundles get contaminated with server utilities, and standalone Nitro tasks fail on Vue runtime dependencies. ```typescript // shared/utils/validation.ts - ANTI-PATTERN: Leaking Vue reactive primitives into shared domain import { ref } from 'vue'; // Breaks Nitro runtime when used in standalone server tasks import { getQuery } from 'h3'; // Breaks client-side bundle in app/ export const validationErrors = ref<string[]>([]); export function validateQueryParam(event: any, key: string): boolean { const query = getQuery(event); if (!query[key]) { validationErrors.value.push(`Missing ${key}`); return false; } return true; } ``` #### Production Standard (Correct) > **Standard**: The shared utility relies purely on universal schema parsing without framework or environment-specific imports, making it safely consumable by both `app/` (Vue components) and `server/` (Nitro routes). ```typescript // shared/utils/validation.ts - PRODUCTION-GRADE: Pure, framework-agnostic schema import { z } from 'zod'; export const QuerySchema = z.object({ userId: z.string().uuid(), locale: z.enum(['en', 'es', 'fr']).default('en') }); export type ValidatedQuery = z.infer<typeof QuerySchema>; export function parseQueryParams(input: Record<string, unknown>): z.SafeParseReturnType<unknown, ValidatedQuery> { return QuerySchema.safeParse(input); } ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Server Engine Isolation & Shared Directory Boundary Enforcements defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architecture and runtime boundaries between Nuxt 4's app/ directory, Nitro server/ runtime, and the polymorphic shared/ directory. Prohibits module-scoped mutable state, cross-boundary runtime imports, and non-isolated server-side hydration traps that cause cross-request state pollution in production SSR. 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: Module-Scoped Mutable Singletons and Cross-Boundary Runtime Leaks across Nuxt 4 app/, server/, and shared/ Directories 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	Module-Scoped Mutable Singletons and Cross-Boundary Runtime Leaks across Nuxt 4 app/, server/, and shared/ Directories	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 state to the request lifecycle using Nuxt `useState()` in `app/` or `event.context` in `server/`

Engineers MUST ALWAYS isolate state to the request lifecycle using Nuxt `useState()` in `app/` or `event.context` in `server/`; module-level mutable variables (`let`, `new Map()`, `ref()`) at file scope are strictly forbidden.

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.