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

--- description: Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation - Enforce strict execution boundary isolation between Nuxt 4's app/, server/ (Nitro engine), and shared/ directory hierarchies. Prevent cross-request state contamination in concurrent SSR rendering and eliminate client/server module boundary leakage. 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-ssr-boundary-isolation" --- # Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-Scoped Mutable State in Nitro Handlers and Impure Cross-Boundary Imports in Nuxt 4 shared/ ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architectural patterns. Mandate absolute isolation between the client-oriented `app/` directory, Nitro v2's `server/` directory, and isomorphic code in `shared/`. Prevent cross-request state pollution, server-side secret leakage, and hydration mismatches caused by un-isolated SSR singletons. ## Strict Guidelines - Engineers MUST ALWAYS organize Nuxt 4 applications using the explicit `app/`, `server/`, and `shared/` directory layout, adhering to `future: { compatibilityVersion: 4 }`. - Engineers MUST NOT declare mutable module-level variables (singletons) in Nitro server routes, middleware, or server utilities; all per-request state MUST be scoped to H3's `event.context`. - Engineers MUST keep the `shared/` directory strictly pure and isomorphic; `shared/` code MUST NOT import Node.js built-ins, Nitro event handlers, Vue reactive primitives (`ref`, `reactive`), or browser-only APIs. - Services handling SSR state in `app/` MUST use Nuxt's `useState()` or properly instantiated Pinia stores within a request scope; global singletons or direct module-scoped reactive variables are strictly prohibited. - Nitro server handlers MUST NEVER import code from `app/`, and components/composables in `app/` MUST NEVER import code directly from `server/`. - Code MUST use runtime config (`useRuntimeConfig(event)`) inside Nitro handlers and guard sensitive keys under `runtimeConfig` instead of leaking them to `runtimeConfig.public`. - Data returned from Nitro handlers to client composables (`useFetch`, `useAsyncData`) MUST be JSON-serializable; engineers MUST NOT return non-serializable instances (e.g., class instances, Symbols, raw stream handles). ## Bad vs Good Implementations ### Prevent Cross-Request State Pollution in Nitro Server Handlers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Nitro runs as a persistent server process in production (Node/Bun/Workers). Global module-level variables persist across requests, causing critical cross-request data leaks where user A's authenticated session is returned to user B. ```typescript // server/api/user/session.ts // ANTI-PATTERN: Module-level state is shared across concurrent incoming requests in Nitro let currentUserSession: { userId: string; roles: string[] } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (token) { // Mutates module singleton; Request B will read or overwrite Request A's session data currentUserSession = await verifySession(token); } return { session: currentUserSession }; }); ``` #### Production Standard (Correct) > **Standard**: Attaching request-specific metadata to `event.context` guarantees lifecycle isolation. The data is garbage-collected at the end of the request and cannot leak between concurrent connections. ```typescript // server/api/user/session.ts // PRODUCTION FIX: Bind per-request data exclusively to event.context export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } // Scoped exclusively to the current H3Event lifecycle event.context.userSession = await verifySession(token); return { session: event.context.userSession }; }); ``` ### Strict Isomorphic Boundaries in the shared/ Directory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing Vue reactivity or server-only configuration into `shared/` breaks client-server boundary rules. It risks pulling Vue internals into pure Nitro worker bundles or leaking server-only credentials to the client bundle. ```typescript // shared/utils/validators.ts // ANTI-PATTERN: Polluting isomorphic shared/ directory with Vue reactivity and Nitro context import { ref } from 'vue'; // Breaks Nitro runtime imports import { useRuntimeConfig } from '#imports'; // Resolves differently in client vs server export const cachedTenant = ref<string | null>(null); export function getTenantDbUrl() { // Leaks server private config into isomorphic bundle const config = useRuntimeConfig(); return config.databaseUrl; } ``` #### Production Standard (Correct) > **Standard**: The `shared/` directory should only house pure schemas, validation functions, and type definitions that evaluate deterministically without environment-dependent dependencies. ```typescript // shared/types/tenant.ts // PRODUCTION FIX: Pure, side-effect-free types and validation schemas import { z } from 'zod'; export const TenantConfigSchema = z.object({ tenantId: z.string().uuid(), subdomain: z.string().min(3), active: z.boolean() }); export type TenantConfig = z.infer<typeof TenantConfigSchema>; export function formatTenantPrefix(tenantId: string): string { return `tenant_${tenantId.replace(/-/g, '_')}`; } ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Server Engine, Shared Directory Boundaries, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforce strict execution boundary isolation between Nuxt 4's app/, server/ (Nitro engine), and shared/ directory hierarchies. Prevent cross-request state contamination in concurrent SSR rendering and eliminate client/server module boundary leakage. 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: Module-Scoped Mutable State in Nitro Handlers and Impure Cross-Boundary Imports in Nuxt 4 shared/ 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	Module-Scoped Mutable State in Nitro Handlers and Impure Cross-Boundary Imports in Nuxt 4 shared/	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 organize Nuxt 4 applications using the explicit `app/`, `server/`, and `shared/` directory layout, adhering to `future

Engineers MUST ALWAYS organize Nuxt 4 applications using the explicit `app/`, `server/`, and `shared/` directory layout, adhering to `future: { compatibilityVersion: 4 }`.

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.