Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standards

--- description: Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standards - Enforces strict architectural boundaries and execution context isolation in Nuxt 4, isolating Nitro server engine logic from the app/ directory via the root shared/ boundary. Prevents catastrophic cross-request state pollution during SSR hydration, illegal cross-boundary runtime imports, and leaks of server-only secrets into client bundles. 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-directory-state-isolation" --- # Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standards > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-Request SSR State Pollution via Nitro Module-Level Singletons and Direct App-to-Server Imports ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 production standards. You mandate absolute boundary isolation between the Nuxt 4 `app/` directory (Vue presentation runtime), `server/` directory (Nitro v2 engine), and `shared/` directory (universal zero-side-effect schemas and types). Enforce per-request context scoping in Nitro event handlers to prevent cross-request memory leaks and multi-tenant data contamination during SSR. ## Strict Guidelines - Engineers MUST ALWAYS isolate universal contracts, Zod schemas, and pure utility functions into the root `shared/` directory, imported using the `~shared` or `#shared` alias. - Engineers MUST NOT import any file from `server/` directly into `app/`, as this bypasses Nitro compilation barriers and risks bundling server secrets into client artifacts. - Engineers MUST NEVER declare mutable state (e.g., `let cache = {}`, `const session = reactive({})`) in module scope within `server/api/*` or `server/middleware/*`; state MUST be explicitly scoped to `event.context` per request. - Code MUST use `useState<T>()` exclusively within the Vue application lifecycle (`app/`) to avoid hydration mismatches, and MUST NEVER use `useState` inside Nitro handlers (`server/`). - Nitro event handlers MUST return typed responses validated via `shared/` schemas, utilizing `readValidatedBody` or `getValidatedQuery` from `h3` rather than unvalidated accessors. - Services interacting with external datasources MUST instantiate clients per request or utilize thread-safe connection pooling attached to Nitro runtime hooks via `nitroApp.hooks`. ## Bad vs Good Implementations ### Nitro Server Route State Pollution vs. Per-Request Context Scoping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables in module scope within Nitro handlers creates a shared singleton across all incoming HTTP requests. Under concurrent multi-user load, User B will read or overwrite User A's session context, leading to security breaches and cross-request state contamination. ```typescript // server/api/user/profile.get.ts import { defineEventHandler, getQuery } from 'h3'; // CRITICAL FLAW: Module-level mutable state leaks across concurrent requests in Nitro SSR engine let currentUserSession: { userId?: string; role?: string } = {}; export default defineEventHandler(async (event) => { const query = getQuery(event); currentUserSession.userId = query.userId as string; currentUserSession.role = 'member'; // Subsequent concurrent requests will read/overwrite this identical shared instance const profile = await fetchUserProfile(currentUserSession.userId); return { profile, session: currentUserSession }; }); async function fetchUserProfile(id: string) { return { id, name: 'Alice' }; } ``` #### Production Standard (Correct) > **Standard**: Validates inputs strictly using the `#shared` schema contract and eliminates module singletons. Data is isolated to local scope and the `event.context` lifecycle, guaranteeing request hermeticity during SSR. ```typescript // shared/types/user.ts import { z } from 'zod'; export const UserProfileSchema = z.object({ userId: z.string().uuid(), role: z.enum(['admin', 'member', 'guest']) }); export type UserProfile = z.infer<typeof UserProfileSchema>; // server/api/user/profile.get.ts import { defineEventHandler, getValidatedQuery, createError } from 'h3'; import { UserProfileSchema } from '#shared/types/user'; export default defineEventHandler(async (event) => { // Invariant: Query parameters validated against shared schema, scoped strictly to the H3Event const query = await getValidatedQuery(event, (data) => UserProfileSchema.pick({ userId: true }).safeParse(data) ); if (!query.success) { throw createError({ statusCode: 400, statusMessage: 'Invalid userId parameter', data: query.error.format() }); } // State is localized to the execution frame and event context const session = event.context.auth ?? { role: 'member' }; const profile = await fetchUserProfile(query.data.userId); return { profile, role: session.role }; }); async function fetchUserProfile(id: string) { return { id, name: 'Alice' }; } ``` ### Nuxt 4 Direct Cross-Boundary Import vs. Shared Directory Extraction #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing server-side utilities into the Nuxt 4 `app/` presentation tree breaks bundler tree-shaking, pulls Node.js-only dependencies into the browser bundle, and frequently leaks encryption algorithms, salts, or server database types directly to the client. ```typescript // app/composables/useUser.ts import { ref } from 'vue'; // CRITICAL ARCHITECTURAL VIOLATION: Importing directly from server directory into app runtime import { hashPassword, decryptToken } from '../../server/utils/crypto'; import type { UserRecord } from '../../server/types/db'; export function useUser() { const user = ref<UserRecord | null>(null); const verifyClientSide = (pwd: string) => hashPassword(pwd); return { user, verifyClientSide }; } ``` #### Production Standard (Correct) > **Standard**: Universal utilities are moved to `#shared`, ensuring no server-only runtime dependencies enter client bundles. SSR-compatible hydration state is handled strictly via Nuxt's `useState()` key-scoping. ```typescript // shared/utils/validation.ts - Zero side-effects, safe for both client and Nitro export const isValidUsername = (username: string): boolean => { return /^[a-zA-Z0-9_-]{3,16}$/.test(username); }; // app/composables/useUser.ts import { useState } from '#imports'; import { isValidUsername } from '#shared/utils/validation'; export interface ClientSafeUser { id: string; username: string; } export function useUser() { // Nuxt-safe SSR hydrated state const user = useState<ClientSafeUser | null>('user-state', () => null); const validate = (name: string): boolean => { return isValidUsername(name); }; return { user, validate }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standards

Nuxt 4 Nitro Server Engine & Shared Directory State Isolation Standards defines an industrial-grade behavioral standard for frontend engineering. Enforces strict architectural boundaries and execution context isolation in Nuxt 4, isolating Nitro server engine logic from the app/ directory via the root shared/ boundary. Prevents catastrophic cross-request state pollution during SSR hydration, illegal cross-boundary runtime imports, and leaks of server-only secrets into client bundles. 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: Cross-Request SSR State Pollution via Nitro Module-Level Singletons and Direct App-to-Server 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	Cross-Request SSR State Pollution via Nitro Module-Level Singletons and Direct App-to-Server 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 universal contracts, Zod schemas, and pure utility functions into the root `shared/` directory, imported using the `~shared` or `#shared` alias.

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.