Nuxt 4 App Directory Restructuring, Nitro v2 Boundaries, and SSR State Isolation

--- description: Nuxt 4 App Directory Restructuring, Nitro v2 Boundaries, and SSR State Isolation - Enforces strict boundary isolation between Nuxt 4 app/ runtime, Nitro v2 server runtime, and the shared/ directory. Eliminates cross-request state pollution during SSR hydration and prevents server-only secrets or Node.js primitives from leaking into client-accessible shared modules. globs: app/**/*.{vue,ts,js}, 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-production-standard" --- # Nuxt 4 App Directory Restructuring, Nitro v2 Boundaries, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Cross-Request State Leaks and Server Secret Bundling in Nuxt 4 Shared/ Modules ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 and Nitro v2 architecture. Mandate absolute isolation between the 'app/' directory (Vue application runtime), 'server/' directory (Nitro engine), and 'shared/' directory (pure isomorphic contracts). Prevent cross-request state contamination in SSR by eliminating module-scope state and prohibiting server-only dependencies inside shared modules. ## Strict Guidelines - Engineers MUST ALWAYS migrate root frontend directories (components, composables, pages, layouts, middleware) into the 'app/' directory conforming to Nuxt 4 structural topology. - Engineers MUST NEVER declare module-level mutable variables (`let`, `var`, `const state = ref()`) outside composable functions or Nitro request handlers; all SSR state MUST be encapsulated via `useState()` in 'app/' or `event.context` in Nitro. - Code in the 'shared/' directory MUST be strictly isomorphic: pure functions, Zod schemas, TypeScript types, and utilities with ZERO Node.js runtime imports (e.g., 'fs', 'crypto', 'path') or browser globals (e.g., 'window', 'document'). - Services in 'server/' MUST access contextual execution state via H3 `H3Event` (`event.context`) and MUST NOT store per-request mutations in Nitro module globals or singletons. - Components NEVER import directly from 'server/' or expose Nitro-only runtime configurations to client hydrators; cross-layer communication MUST occur through typed Nitro API endpoints or validated event streaming. - Engineers MUST configure 'compatibilityDate' explicitly in 'nuxt.config.ts' and verify that 'future.compatibilityVersion: 4' runtime standards are maintained. ## Bad vs Good Implementations ### Module-Level Mutable State in SSR (Cross-Request State Contamination) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring a Vue `ref` at the top level of a module in SSR causes all concurrent HTTP requests to share the same mutable memory reference. Request A can overwrite Request B's authentication session, resulting in high-severity data leakage across tenants. ```typescript // app/composables/useUserSession.ts import { ref } from 'vue'; // ANTI-PATTERN: Module-scope ref shared across concurrent SSR threads in Node/Nitro const globalUser = ref<{ id: string; role: string } | null>(null); export const useUserSession = () => { const setUser = (user: { id: string; role: string }) => { globalUser.value = user; }; return { user: globalUser, setUser }; }; ``` #### Production Standard (Correct) > **Standard**: Using `useState` registers a unique state entry bound to the specific Nuxt app context for that request. It is automatically serialized and safely dehydrated into the client payload without polluting the server process memory. ```typescript // app/composables/useUserSession.ts export interface UserSession { id: string; role: string; } export const useUserSession = () => { // GUARANTEED: useState generates SSR-safe, request-isolated hydratable state key const user = useState<UserSession | null>('auth:user-session', () => null); const setUser = (newUser: UserSession | null) => { user.value = newUser; }; return { user, setUser }; }; ``` ### Leaking Server-Only Runtime Primitives in the Shared Directory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing 'node:crypto' or embedding server secrets into the 'shared/' directory breaks client bundling or leaks server cryptographic constructs into the browser payload during Nuxt 4 isomorphic bundling. ```typescript // shared/utils/crypto.ts import { createHash } from 'node:crypto'; // ANTI-PATTERN: Leaking Node.js runtime into shared context export const generateHash = (value: string): string => { return createHash('sha256').update(value).digest('hex'); }; export interface AppMetadata { envSecret: string; // Server secret schema embedded into shared client-accessible contract } ``` #### Production Standard (Correct) > **Standard**: Keeps 'shared/' strictly agnostic to the underlying runtime environment. It contains pure data contracts, interfaces, and schemas valid across both Nitro v2 server engines and browser client bundles. ```typescript // shared/utils/contracts.ts import { z } from 'zod'; // GUARANTEED: Isomorphic schema validation and contract definitions export const UserPayloadSchema = z.object({ id: z.string().uuid(), displayName: z.string().min(2).max(50), email: z.string().email() }); export type UserPayload = z.infer<typeof UserPayloadSchema>; // Node-specific hashing logic stays strictly within 'server/utils/crypto.ts' // Client-side hashing (if needed) uses SubtleCrypto Web API within 'app/utils/' ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Nuxt 4 App Directory Restructuring, Nitro v2 Boundaries, and SSR State Isolation

Nuxt 4 App Directory Restructuring, Nitro v2 Boundaries, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation between Nuxt 4 app/ runtime, Nitro v2 server runtime, and the shared/ directory. Eliminates cross-request state pollution during SSR hydration and prevents server-only secrets or Node.js primitives from leaking into client-accessible shared modules. 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 Cross-Request State Leaks and Server Secret Bundling in Nuxt 4 Shared/ Modules 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 Cross-Request State Leaks and Server Secret Bundling in Nuxt 4 Shared/ Modules	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 migrate root frontend directories (components, composables, pages, layouts, middleware) into the 'app/' directory conforming to Nuxt 4 structural topology.

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.