Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR State Isolation

--- description: Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR State Isolation - Enforces strict boundaries in Nuxt 4 projects between the restructured app/ client workspace, Nitro v2 server/ engine, and shared/ isomorphic directory. Prevents cross-boundary leakage of server secrets into client bundles, stops module-level mutable state leaks across concurrent SSR requests, and guarantees deterministic client-side hydration. 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-hydration-isolation" --- # Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR State Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Cross-boundary module imports and un-isolated global server singletons causing SSR cross-request state pollution and hydration mismatches ## System Constraints You are a Principal Software Architect enforcing Nuxt 4 architectural purity, Nitro v2 execution integrity, and SSR state safety. Enforce the Nuxt 4 folder hierarchy (app/, server/, shared/), forbid top-level mutable runtime singletons on the server, eliminate client-side pollution from Nitro routes, and mandate safe hydration patterns. ## Strict Guidelines - Engineers MUST house client-side code strictly within 'app/', server logic within 'server/', and isomorphic types/utilities within 'shared/'. - Engineers MUST NOT import any module from 'server/' into 'app/' or 'shared/'; server access MUST occur exclusively via typed `$fetch` or `useFetch` calling Nitro endpoints. - Engineers MUST NOT define module-scoped mutable variables (e.g., `let currentUser`, `const sessionStore = new Map()`) in Nitro event handlers or Vue composables, as these leak data across concurrent requests in long-running Node/Bun/Worker SSR runtimes. - Code MUST use `event.context` in Nitro handlers and `useState()` or Pinia with request-scoped isolation in Vue components to preserve multi-tenant boundary safety. - Engineers MUST ensure that any code imported into 'shared/' is completely runtime-agnostic, containing zero Node built-ins (`fs`, `crypto`, `path`) and zero browser globals (`window`, `document`, `localStorage`). - Components NEVER use `ref()` or `reactive()` outside setup functions for SSR-rendered state; all client-server bridge state MUST be initialized with `useState(key, init)` to ensure serialized payload parity during hydration. ## Bad vs Good Implementations ### Nitro Server Route State Leak vs Request Context Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring 'cachedUser' at the module root creates a shared singleton across all server requests. Request B will read the user authenticated by Request A, causing critical tenant data contamination. ```typescript // server/api/profile.ts // ANTI-PATTERN: Top-level mutable variable leaks across concurrent user requests in Node/Nitro runtime let cachedUser: { id: string; role: string } | null = null; export default defineEventHandler(async (event) => { const token = getHeader(event, 'authorization'); if (!cachedUser && token) { cachedUser = await verifyAndFetchUser(token); } return { user: cachedUser }; }); async function verifyAndFetchUser(token: string) { return { id: 'usr_123', role: 'admin' }; } ``` #### Production Standard (Correct) > **Standard**: State is scoped to the individual H3Event lifecycle (`event.context`). Every concurrent request evaluates independently without leaking cross-user state. ```typescript // server/api/profile.get.ts import { defineEventHandler, getHeader, createError } from 'h3'; import type { UserProfile } from '~~/shared/types/user'; export default defineEventHandler(async (event): Promise<{ user: UserProfile }> => { // INVARIANT: State is isolated to the H3Event context lifetime const token = getHeader(event, 'authorization'); if (!token) { throw createError({ statusCode: 401, statusMessage: 'Unauthorized' }); } const user = await event.context.auth?.getUser(token) ?? await verifyAndFetchUser(token); event.context.user = user; return { user }; }); async function verifyAndFetchUser(token: string): Promise<UserProfile> { return { id: 'usr_123', role: 'admin' }; } ``` ### Nuxt 4 Shared Directory and Safe SSR Hydration State #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Importing from 'server/' into 'app/' breaches runtime boundaries and bundles server secrets into client assets. Using top-level `ref` breaks per-request hydration isolation across SSR runs. ```typescript // app/composables/useSession.ts // ANTI-PATTERN: Module-scoped reactive state triggers hydration mismatches and cross-client leakage import { ref } from 'vue'; import { verifyTokenOnServer } from '~~/server/utils/crypto'; // Fatal import leak const globalToken = ref<string | null>(null); export const useSession = () => { return { token: globalToken }; }; ``` #### Production Standard (Correct) > **Standard**: Types are shared via the runtime-agnostic 'shared/' directory. The composable leverages 'useState', which Nuxt 4 binds to the SSR request context and hydrates deterministically on the client without bundling server dependencies. ```typescript // shared/types/session.ts export interface SessionState { token: string | null; expiresAt: number | null; } // app/composables/useSession.ts import type { SessionState } from '~~/shared/types/session'; export const useSession = () => { // INVARIANT: useState serializes state into Nuxt payload for lossless hydration const session = useState<SessionState>('auth:session', () => ({ token: null, expiresAt: null, })); const setSession = (newState: SessionState) => { session.value = newState; }; return { session: readonly(session), setSession, }; }; ```

Architectural Specification & Invariant Rationale

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

Nuxt 4 Nitro Engine, Shared Directory Architecture, and SSR State Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundaries in Nuxt 4 projects between the restructured app/ client workspace, Nitro v2 server/ engine, and shared/ isomorphic directory. Prevents cross-boundary leakage of server secrets into client bundles, stops module-level mutable state leaks across concurrent SSR requests, and guarantees deterministic client-side hydration. 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-boundary module imports and un-isolated global server singletons causing SSR cross-request state pollution and hydration mismatches 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-boundary module imports and un-isolated global server singletons causing SSR cross-request state pollution and hydration mismatches	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 house client-side code strictly within 'app/', server logic within 'server/', and isomorphic types/utilities within 'shared/'.

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.