Nuxt 4 Nitro Server Engine & Shared Directory Production Standard

--- description: Nuxt 4 Nitro Server Engine & Shared Directory Production Standard - Nuxt 4 enforces strict boundary segregation between client UI in the app/ directory, backend endpoints in server/, and universal contracts in shared/. Violating cross-boundary isolation or maintaining module-scoped state in Nitro server handlers causes catastrophic cross-request data corruption and hydration mismatches under concurrent production traffic. Architects must enforce request-isolated H3 event contexts, universal serialization schemas, and strict path-alias boundaries. globs: app/**/*, server/**/*, shared/**/*, nuxt.config.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nuxt-4-nitro-server-engine-shared-directory-production-standard" --- # Nuxt 4 Nitro Server Engine & Shared Directory Production Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Placing mutable module-level state in Nitro event handlers and importing server-only dependencies into client or shared directories. ## System Constraints You are a Nuxt 4 and Nitro v2 architecture specialist enforcing strict SSR lifecycle safety and directory boundaries. You MUST reject any global state in server/ routes and forbid importing Node/Nitro server modules into app/ or shared/ directories. Enforce request-scoped context via H3 event.context and ensure full hydration safety with serializable shared data structures. ## Strict Guidelines - Developers MUST NOT define mutable variables at the module root of Nitro route handlers or middleware; all per-request state MUST be anchored to H3Event.context. - Code placed in the shared/ directory MUST be strictly isomorphic and free of platform-specific runtimes such as Node.js fs, Nitro server utils, or browser-only DOM APIs. - Nuxt 4 client UI components, composables, and pages MUST reside exclusively within the app/ directory and MUST NEVER import modules directly from server/. - Nitro server routes returning payloads for client-side hydration MUST ALWAYS return plain, JSON-serializable objects and avoid circular references or prototype-dependent class instances. - Data shared across client and server boundaries SHOULD ALWAYS be validated at the transport layer using deterministic schemas (such as Zod or ArkType) imported from the shared/ directory. ## Bad vs Good Implementations ### Preventing Cross-Request State Leakage in Nitro Handlers and Hydration Schema #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defining cachedUserProfile at the module level in a Nitro server route creates a severe concurrency vulnerability: concurrent requests from different users overwrite and read each other's data in the Node.js event loop. Additionally, returning a raw Date object causes SSR hydration mismatch when serialized across Nitro and the client app. ```typescript import { defineEventHandler, readBody } from 'h3'; import type { UserProfile } from '~~/shared/types'; // FATAL: Module-scoped state shared across all concurrent requests in Nitro let cachedUserProfile: UserProfile | null = null; export default defineEventHandler(async (event) => { const body = await readBody<{ id: string }>(event); if (!cachedUserProfile || cachedUserProfile.id !== body.id) { // DB fetch simulation cachedUserProfile = { id: body.id, role: 'authenticated', sessionTimestamp: new Date() // Non-serializable class instance causing hydration mismatch }; } return cachedUserProfile; }); ``` #### Production Standard (Correct) > **Standard**: The handler validates input with schema parsing from shared boundaries, eliminates all module-scoped mutable variables to ensure thread-safe concurrency in Nitro, stores context directly on the request event, and outputs an ISO string ensuring idempotent client-server SSR hydration. ```typescript import { defineEventHandler, readValidatedBody, createError } from 'h3'; import { z } from 'zod'; import type { UserProfileResponse } from '~~/shared/types'; const userProfileRequestSchema = z.object({ id: z.string().uuid() }); export default defineEventHandler(async (event): Promise<UserProfileResponse> => { const result = await readValidatedBody(event, (body) => userProfileRequestSchema.safeParse(body) ); if (!result.success) { throw createError({ statusCode: 400, statusMessage: 'Bad Request', data: result.error.flatten() }); } // Request-isolated state: Attach exclusively to event.context const { id } = result.data; // Isolated per-request retrieval without module-level leaks const user = { id, role: 'authenticated' as const, sessionTimestampIso: new Date().toISOString() // JSON-serializable string for hydration stability }; event.context.user = user; return user; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine & Shared Directory Production Standard

Nuxt 4 Nitro Server Engine & Shared Directory Production Standard defines an industrial-grade behavioral standard for frontend engineering. Nuxt 4 enforces strict boundary segregation between client UI in the app/ directory, backend endpoints in server/, and universal contracts in shared/. Violating cross-boundary isolation or maintaining module-scoped state in Nitro server handlers causes catastrophic cross-request data corruption and hydration mismatches under concurrent production traffic. Architects must enforce request-isolated H3 event contexts, universal serialization schemas, and strict path-alias boundaries. 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: Placing mutable module-level state in Nitro event handlers and importing server-only dependencies into client or 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	Placing mutable module-level state in Nitro event handlers and importing server-only dependencies into client or 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:

Developers MUST NOT define mutable variables at the module root of Nitro route handlers or middleware

Developers MUST NOT define mutable variables at the module root of Nitro route handlers or middleware; all per-request state MUST be anchored to H3Event.context.

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.