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

--- description: Nuxt 4 Nitro Engine Boundaries, Shared Directory Purity, and SSR State Isolation - Enforces architectural boundary separation across Nuxt 4's app/ layer, Nitro v2 server engine (server/), and isomorphic domain directory (shared/). Prevents cross-request state pollution, runtime leakage between Vue and Nitro, and SSR state hydration vulnerabilities. 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-architecture" --- # Nuxt 4 Nitro Engine Boundaries, Shared Directory Purity, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level State Pollution and Illegal Boundary Cross-Imports in Nuxt 4 ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 Nitro Server Engine and Shared Directory invariants. You must prevent cross-request state pollution, runtime context bleed, and hydration mismatch disasters. Enforce pure isomorphic boundaries in shared/, strict request-scoped execution in server/, and isolated reactive SSR hydration in app/. ## Strict Guidelines - Engineers MUST ALWAYS isolate Nitro request state using 'event.context' or function-scoped closures; top-level mutable variables in 'server/' routes are strictly prohibited due to Node/V8 multi-request memory sharing. - Engineers MUST keep the 'shared/' directory strictly runtime-agnostic; code in 'shared/' MUST NOT import Vue runtime APIs ('ref', 'reactive', 'computed'), Nitro APIs ('defineEventHandler', 'readBody'), or Node.js-only builtins. - Engineers MUST place all Vue UI application code (pages, components, composables, plugins, layouts) inside 'app/' when operating in Nuxt 4 compatibility mode, maintaining total decoupling from 'server/'. - Engineers MUST NEVER import client-side Vue composables ('useState', 'useFetch', 'useRoute') into Nitro route handlers or Nitro plugins. - Engineers MUST use 'useState()' exclusively within 'app/' setup context for SSR state transfer and NEVER initialize reactive singletons in module root scope. - Code MUST validate incoming Nitro request bodies using portable schemas (e.g., Zod) declared in 'shared/' to guarantee compile-time and run-time contract alignment across client and server. ## Bad vs Good Implementations ### Prevent Cross-Request State Leakage in Nitro Server Routes #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In persistent server environments (Node.js, Bun), Nitro server handlers execute within a long-lived process. Declaring mutable variables in module scope caches state across multiple incoming HTTP requests, creating critical data leaks between concurrent users. ```typescript // server/api/user/session.ts - ANTI-PATTERN: Top-level mutable state leaks across requests in Node/Nitro runtime let cachedAuthUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token && !cachedAuthUser) { cachedAuthUser = await verifyAuthToken(token); } // CRITICAL SECURITY FLAW: Subsequent concurrent requests by other users receive cachedAuthUser! return { user: cachedAuthUser }; }); ``` #### Production Standard (Correct) > **Standard**: Request state is completely isolated inside H3/Nitro event.context. Every request generates a distinct H3Event instance, eliminating cross-request data corruption. ```typescript // server/api/user/session.ts - PRODUCTION FIX: Strictly request-scoped isolation via event.context export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Request-isolated computation; attach exclusively to event.context if middleware shared if (!event.context.user) { event.context.user = await verifyAuthToken(token); } return { user: event.context.user }; }); ``` ### Shared Directory Purity vs. Runtime Bleed #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Vue reactivity primitives or client libraries into the shared/ directory pollutes the isomorphic boundary, breaking non-Vue consumers like Nitro server endpoints, CLI migration tools, and background tasks. ```typescript // shared/types/user.ts - ANTI-PATTERN: Leaking Vue reactivity into shared domain models import { ref } from 'vue'; import { z } from 'zod'; export const userSchema = z.object({ id: z.string().uuid(), name: z.string().min(1) }); // Leaking Vue reactive dependency into shared boundary breaks Nitro/worker bundles export const activeUserRef = ref<z.infer<typeof userSchema> | null>(null); ``` #### Production Standard (Correct) > **Standard**: The shared directory remains 100% portable, free of Vue or Nitro runtime dependencies, and can be safely imported across app/ components and server/ handlers. ```typescript // shared/types/user.ts - PRODUCTION FIX: Pure isomorphic schema and runtime-agnostic types import { z } from 'zod'; export const UserSchema = z.object({ id: z.string().uuid(), name: z.string().min(1), email: z.string().email() }); export type User = z.infer<typeof UserSchema>; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Engine Boundaries, Shared Directory Purity, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural boundary separation across Nuxt 4's app/ layer, Nitro v2 server engine (server/), and isomorphic domain directory (shared/). Prevents cross-request state pollution, runtime leakage between Vue and Nitro, and SSR state hydration vulnerabilities. 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: Global Module-Level State Pollution and Illegal Boundary Cross-Imports in Nuxt 4 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	Global Module-Level State Pollution and Illegal Boundary Cross-Imports in Nuxt 4	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 Nitro request state using 'event.context' or function-scoped closures

Engineers MUST ALWAYS isolate Nitro request state using 'event.context' or function-scoped closures; top-level mutable variables in 'server/' routes are strictly prohibited due to Node/V8 multi-request memory sharing.

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.