Nuxt 4 Nitro Server Engine & Shared Directory Cross-Boundary Isolation

--- description: Nuxt 4 Nitro Server Engine & Shared Directory Cross-Boundary Isolation - Nuxt 4 formalizes the `app/` and `shared/` directory structures alongside Nitro v2 server routes. Shared code between Nitro and the Vue rendering engine must remain strictly stateless, pure, and free from runtime-specific globals, while client/server state hydration must occur exclusively through `useState` or context-isolated stores to avoid multi-tenant cross-request state pollution during 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/nuxt-4-nitro-shared-directory-isolation-standard" --- # Nuxt 4 Nitro Server Engine & Shared Directory Cross-Boundary Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Singletons in Nitro/Shared Directories and Leaking Server Context into SSR Hydration ## System Constraints You are a Principal Engineer enforcing Nuxt 4 Nitro Server Engine & Shared Directory architectural invariants. Mandate zero cross-request memory leaks in Nitro event handlers, enforce absolute boundary hygiene in `shared/` modules, prevent server execution leaks into Vue client bundles, and ensure SSR hydration safety without un-isolated global reactive state. ## Strict Guidelines - Engineers MUST ALWAYS house application code strictly inside `app/` and server routes within `server/`, utilizing `shared/` exclusively for isomorphic, pure utilities, schemas, and type definitions. - Engineers MUST NOT declare mutable global state or module-scoped reactive variables in `shared/` or Nitro `server/` handlers, as Node/runtime workers persist module singletons across concurrent requests, causing cross-tenant data leaks. - Code inside `shared/` MUST NOT import Nitro-specific APIs (`defineEventHandler`, `getRouterParam`, `readBody`) or Nuxt/Vue-specific composables (`useState`, `useFetch`, `ref`, `computed`). - Server route handlers MUST encapsulate state strictly within the H3 `H3Event` context using `event.context` or request-scoped helpers, never mutating module-level variables. - Components NEVER initialize SSR hydration state using raw module-scoped `ref()` or standard global JavaScript objects; dynamic state hydration MUST utilize `useState()` or request-isolated Pinia stores. ## Bad vs Good Implementations ### Module-Scoped Stateful Pollution in Nitro Route Handler vs Context Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `cachedAuthToken` at the module root in a Nitro server route creates a severe cross-request state leak. Under concurrent traffic, Request B overwrites the token while Request A is awaiting an asynchronous operation, serving Tenant B's credentials to Tenant A. ```typescript // server/api/user-session.ts import { defineEventHandler, getHeader } from 'h3'; // CRITICAL ANTI-PATTERN: Module-scoped state shared across all concurrent SSR requests let cachedAuthToken: string | null = null; export default defineEventHandler(async (event) => { cachedAuthToken = getHeader(event, 'authorization') ?? null; // Asynchronous wait simulates external verification; concurrent requests overwrite cachedAuthToken await new Promise((resolve) => setTimeout(resolve, 50)); return { token: cachedAuthToken }; }); ``` #### Production Standard (Correct) > **Standard**: Variables are bound exclusively to the asynchronous execution context and `event.context`. Concurrent requests are completely isolated in memory, eliminating multi-tenant cross-contamination. ```typescript // server/api/user-session.ts import { defineEventHandler, getHeader, createError } from 'h3'; export default defineEventHandler(async (event) => { // Invariant: Isolate request state strictly within local scope or event.context const authToken = getHeader(event, 'authorization'); if (!authToken) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized: Missing Authorization header', }); } // Store transient request data strictly within event.context if middleware propagation is required event.context.auth = { token: authToken }; await new Promise((resolve) => setTimeout(resolve, 50)); return { token: event.context.auth.token }; }); ``` ### Shared Directory Anti-Pattern vs Pure Isomorphic Schema Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: `shared/` must be runtime-agnostic. Importing `h3` causes build bloat or client runtime failures, while importing Vue reactivity (`ref`) pollutes server modules with reactive proxies and creates state leaks across server calls. ```typescript // shared/utils/validators.ts import { ref } from 'vue'; // LEAK: Vue runtime imported into Nitro context import { getQuery } from 'h3'; // LEAK: Nitro runtime imported into client bundle export const validationState = ref(false); export function validatePagination(event: any) { const query = getQuery(event); validationState.value = Number(query.limit) <= 100; return validationState.value; } ``` #### Production Standard (Correct) > **Standard**: The shared utility depends strictly on isomorphic libraries (such as Zod). It maintains zero runtime dependencies on either `h3` or `vue`, enabling tree-shakable, type-safe execution in both Nitro handlers and Vue components. ```typescript // shared/utils/validators.ts import { z } from 'zod'; // Pure, runtime-agnostic validation contract usable in both app/ and server/ export const PaginationSchema = z.object({ page: z.coerce.number().int().positive().default(1), limit: z.coerce.number().int().min(1).max(100).default(20), }); export type PaginationQuery = z.infer<typeof PaginationSchema>; export function validatePaginationInput(raw: unknown): PaginationQuery { return PaginationSchema.parse(raw); } ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Server Engine & Shared Directory Cross-Boundary Isolation defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 formalizes the `app/` and `shared/` directory structures alongside Nitro v2 server routes. Shared code between Nitro and the Vue rendering engine must remain strictly stateless, pure, and free from runtime-specific globals, while client/server state hydration must occur exclusively through `useState` or context-isolated stores to avoid multi-tenant cross-request state pollution during 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: Global Singletons in Nitro/Shared Directories and Leaking Server Context into SSR Hydration 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 Singletons in Nitro/Shared Directories and Leaking Server Context into SSR Hydration	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 house application code strictly inside `app/` and server routes within `server/`, utilizing `shared/` exclusively for isomorphic, pure utilities, schemas, and type definitions.

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.