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

--- description: Nuxt 4 Nitro Engine, Shared Directory Boundaries, and SSR Isolation - Enforces strict boundary isolation between Nuxt 4's app/ layer, server/ (Nitro engine), and shared/ directory. Prevents catastrophic cross-request SSR state contamination, server secret leakage to the client bundle, and illegal cross-boundary runtime imports. 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-boundary-standard" --- # Nuxt 4 Nitro Engine, Shared Directory Boundaries, and SSR Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Mutable SSR Singletons & Leaking Nitro Server Context Across Shared Directory Boundaries ## System Constraints You are a Principal Software Architect enforcing architectural integrity in Nuxt 4. Mandate strict isolation between the app/ presentation tier, server/ (Nitro runtime), and shared/ isomorphic domain layer. Strictly reject cross-request state pollution, top-level reactive SSR globals, and un-sanitized context transfers between client and server. ## Strict Guidelines - Engineers MUST ALWAYS isolate UI code inside `app/`, server handlers inside `server/`, and pure agnostic logic inside `shared/` when Nuxt 4 compatibility mode (`future.compatibilityVersion: 4`) is active. - Engineers MUST NEVER declare global mutable state (e.g., module-scoped `let`, `ref()`, `reactive()`, or top-level maps) in `server/` routes, composables, or `shared/` modules, as this leaks data between concurrent SSR requests. - Engineers MUST ALWAYS encapsulate SSR-hydrated state using `useState()` inside `app/` and request-scoped metadata inside `event.context` within Nitro `server/` event handlers. - Engineers MUST NOT import server-only modules, runtime configs (`useRuntimeConfig().serverSecret`), Node.js built-ins, or Nitro utilities into `app/` or client-executed files. - Code inside `shared/` MUST remain strictly isomorphic: it MUST NEVER reference `window`, `document`, DOM nodes, Vue reactivity, Node.js process APIs, or Nitro event contexts. - Server routes MUST validate payloads using shared validation schemas (e.g., Zod, Valibot) imported strictly from `shared/` to maintain contract consistency between client and Nitro. ## Bad vs Good Implementations ### Preventing SSR Cross-Request Pollution and Enforcing Nuxt 4 Directory Boundaries #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring mutable variables (`cachedUserSession`) in the module root of a Nitro event handler persists across subsequent incoming HTTP requests in a long-running Node/Bun process, causing critical data breaches where Tenant A sees Tenant B's session. Importing from `app/` into `server/` violates architectural layering. ```typescript // server/api/user.ts - CRITICAL: Global module-level state causes cross-request contamination import { userStore } from '~/app/stores/user'; // VIOLATION: Importing app/ store into Nitro server let cachedUserSession: Record<string, any> = {}; // VIOLATION: Shared across all concurrent tenant requests! export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token) { cachedUserSession = await fetchUserFromDb(token); } return cachedUserSession; // Leaks another user's session if request arrives concurrently }); ``` #### Production Standard (Correct) > **Standard**: State is completely isolated: shared contracts exist purely in `shared/`, server logic is contained in `server/api` using request-scoped handlers, and client/SSR state utilizes Nuxt's hydration-safe `useState()` primitive inside `app/` without global singleton leaks. ```typescript // shared/types/user.ts - Pure contracts shared between app/ and server/ export interface UserProfile { id: string; tenantId: string; email: string; } // server/api/user.get.ts - Nitro route leveraging request-scoped event context import type { UserProfile } from '~~/shared/types/user'; export default defineEventHandler(async (event): Promise<UserProfile> => { // Invariant: Isolate request state strictly within Nitro event context const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Scoped strictly to this request invocation - no global pollution const user = await fetchUserFromDb(token); event.context.user = user; return { id: user.id, tenantId: user.tenantId, email: user.email }; }); // app/composables/useUserProfile.ts - Safe SSR-hydrated composable in app/ layer import type { UserProfile } from '~~/shared/types/user'; export const useUserProfile = () => { // Nuxt-managed unique hydration key per request lifecycle return useState<UserProfile | null>('user-profile', () => null); }; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Engine, Shared Directory Boundaries, and SSR Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation between Nuxt 4's app/ layer, server/ (Nitro engine), and shared/ directory. Prevents catastrophic cross-request SSR state contamination, server secret leakage to the client bundle, and illegal cross-boundary runtime imports. 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 Mutable SSR Singletons & Leaking Nitro Server Context Across Shared Directory Boundaries 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 Mutable SSR Singletons & Leaking Nitro Server Context Across Shared Directory Boundaries	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 UI code inside `app/`, server handlers inside `server/`, and pure agnostic logic inside `shared/` when Nuxt 4 compatibility mode (`future.compatibilityVersion

Engineers MUST ALWAYS isolate UI code inside `app/`, server handlers inside `server/`, and pure agnostic logic inside `shared/` when Nuxt 4 compatibility mode (`future.compatibilityVersion: 4`) is active.

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.