Next.js 15 Build-Time Dynamic Server-Only Module Leak Guardrail

--- description: Next.js 15 Build-Time Dynamic Server-Only Module Leak Guardrail - Enforces strict static isolation between Next.js 15 Server Component runtimes and client hydration manifests to prevent inadvertent bundling of secrets, DB clients, and native bindings. Mandates build-time fail-closed poison pills ('server-only') and structural module boundary isolation to eliminate client-side credential exposure and hydration bloat. globs: src/**/*.{ts,tsx}, app/**/*.{ts,tsx}, lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-server-only-module-leak-guardrail" --- # Next.js 15 Build-Time Dynamic Server-Only Module Leak Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Sensitive Server Runtime Modules or Native Secrets into Client Bundles via Transitive Barrel Imports ## System Constraints You are a Principal Software Architect enforcing zero-trust module boundaries between React Server Components (RSC) and Client Hydration manifests in Next.js 15. Your mandate is to eliminate client-side bundle leakage of native bindings, secret keys, and database singletons using strict static analysis, build-time poison pills ('server-only'), and strict barrel file partitioning. ## Strict Guidelines - Engineers MUST ALWAYS include `import 'server-only';` as the immediate first statement in all modules containing secret stores, database clients (e.g., Prisma, Drizzle), native bindings (e.g., sharp, bcrypt), or private environment access. - Engineers MUST NOT create unified barrel files (`index.ts`) that mix client-safe utilities with server-side logic, as bundlers can evaluate or pull whole trees into hydration chunks. - Code SHOULD strictly separate files into distinct directory hierarchies (e.g., `lib/server/*` vs. `lib/client/*`) and enforce ESLint boundaries (`no-restricted-imports`) between client and server layers. - Services MUST serialize and sanitize DTOs across the Server-Client boundary; raw ORM entities containing sensitive metadata or native handles MUST NEVER be passed as props to Client Components. - Components marked with `'use client'` NEVER import modules that directly reference `process.env` secrets or invoke server-side infrastructure libraries. ## Bad vs Good Implementations ### Server Secret Store and ORM Boundary Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mixing a client-safe helper (`formatUserDisplayName`) with Node.js built-ins (`crypto`) and raw server secrets (`SESSION_SECRET`) in a single file without `import 'server-only'` causes client components importing the helper to trigger bundler errors or inadvertently leak secrets into the public client bundle. ```typescript // lib/auth.ts - Mixed module without poison pill, easily leaked via barrel or client import import { db } from './db'; import crypto from 'node:crypto'; export const SESSION_SECRET = process.env.SESSION_SECRET_KEY!; export function formatUserDisplayName(firstName: string, lastName: string): string { return `${firstName} ${lastName}`.trim(); } export async function getDecryptedSessionToken(token: string): Promise<string> { const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(SESSION_SECRET, 'hex'), Buffer.alloc(16)); return decipher.update(token, 'hex', 'utf8') + decipher.final('utf8'); } // components/UserProfile.tsx 'use client'; // FATAL: Imports formatUserDisplayName, pulling node:crypto and SESSION_SECRET into client manifest import { formatUserDisplayName } from '@/lib/auth'; export function UserProfile({ firstName, lastName }: { firstName: string; lastName: string }) { return <div>Welcome, {formatUserDisplayName(firstName, lastName)}</div>; } ``` #### Production Standard (Correct) > **Standard**: The server-side decryption logic is isolated in `lib/server/auth.ts` with `import 'server-only'`, throwing a build-time compile error if any client module touches it. Client-safe formatters live in a separate file, maintaining zero risk of secret leakage. ```typescript // lib/server/auth.ts - Hardened server-only module with poison pill import 'server-only'; import crypto from 'node:crypto'; import { db } from './db'; const SESSION_SECRET = process.env.SESSION_SECRET_KEY; if (!SESSION_SECRET) { throw new Error('FATAL: SESSION_SECRET_KEY environment variable is not defined.'); } export async function getDecryptedSessionToken(token: string): Promise<string> { const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(SESSION_SECRET, 'hex'), Buffer.alloc(16)); return decipher.update(token, 'hex', 'utf8') + decipher.final('utf8'); } // lib/client/formatters.ts - Pure, client-safe utility export function formatUserDisplayName(firstName: string, lastName: string): string { return `${firstName} ${lastName}`.trim(); } // components/UserProfile.tsx 'use client'; import { formatUserDisplayName } from '@/lib/client/formatters'; export function UserProfile({ firstName, lastName }: { firstName: string; lastName: string }) { return <div>Welcome, {formatUserDisplayName(firstName, lastName)}</div>; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Build-Time Dynamic Server-Only Module Leak Guardrail

Next.js 15 Build-Time Dynamic Server-Only Module Leak Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict static isolation between Next.js 15 Server Component runtimes and client hydration manifests to prevent inadvertent bundling of secrets, DB clients, and native bindings. Mandates build-time fail-closed poison pills ('server-only') and structural module boundary isolation to eliminate client-side credential exposure and hydration bloat. 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: Leaking Sensitive Server Runtime Modules or Native Secrets into Client Bundles via Transitive Barrel 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	Leaking Sensitive Server Runtime Modules or Native Secrets into Client Bundles via Transitive Barrel 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 include `import 'server-only'

Engineers MUST ALWAYS include `import 'server-only';` as the immediate first statement in all modules containing secret stores, database clients (e.g., Prisma, Drizzle), native bindings (e.g., sharp, bcrypt), or private environment access.

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.