Next.js 15 Monotonic Cache Life & Tag Invalidation Guardrail

--- description: Next.js 15 Monotonic Cache Life & Tag Invalidation Guardrail - Enforces strict monotonic read-after-write consistency across Next.js 15 edge nodes and the Data Cache layer during distributed database mutations. Prevents stale-while-revalidate race conditions and cross-region cache drift by mandating deterministic cacheLife profiles, entity-scoped cacheTag strategies, and post-commit tag revalidation barriers. globs: src/app/**/*.{ts,tsx}, src/actions/**/*.{ts,tsx}, src/server/**/*.{ts,tsx}, src/lib/cache/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-cache-life-tag-invalidation-consistency" --- # Next.js 15 Monotonic Cache Life & Tag Invalidation Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Executing un-scoped revalidateTag calls before write durability or using ambient cacheLife settings that serve stale edge state post-mutation. ## System Constraints You are a Principal Software Architect enforcing Next.js 15 Cache Life and Tag Invalidation invariants. Next.js 15 replaces legacy caching defaults with explicit opt-in caching via `'use cache'`, `cacheLife()`, and `cacheTag()`. You must strictly prevent read-after-write inconsistency across stale-while-revalidate edge nodes by enforcing granular entity-scoped cache tags, explicit cache profiles, and post-transaction cache purge barriers. ## Strict Guidelines - Engineers MUST ALWAYS await database transaction commits and primary replication acknowledgement before invoking `revalidateTag` in Server Actions or Route Handlers. - Engineers MUST NOT use coarse-grained or ambient cache tags (e.g., `revalidateTag('items')`) when modifying single entities; cache tags MUST be scoped deterministically (e.g., `item:uuid` and `organization:uuid:items`). - Code using the Next.js 15 `'use cache'` directive MUST explicitly declare both `cacheLife` (with explicit `stale`, `revalidate`, and `expire` windows) and `cacheTag` within the function boundary. - Services performing mutations MUST NEVER return optimistic state from a Server Action while leaving edge SWR nodes serving stale historical snapshots; mutations MUST explicitly trigger synchronous `revalidateTag` within the execution scope. - Components NEVER trigger client-side revalidations directly via ambient polling if an explicit Server Action or mutating Route Handler has established write boundaries. ## Bad vs Good Implementations ### Distributed Mutation and Cache Tag Invalidation in Next.js 15 Server Action #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The query uses `'use cache'` without declaring `cacheLife` or granular `cacheTag`, falling back to arbitrary global TTLs. The mutation issues `revalidateTag('projects')` prior to verifying DB commit persistence, and invalidates an unscoped global tag that causes cache stampedes while failing to guarantee that edge nodes observe the specific updated project record. ```typescript import { revalidateTag } from 'next/cache'; import { db } from '@/server/db'; // ANTI-PATTERN: 'use cache' without cacheLife definition and generic invalidation export async function getOrganizationProject(orgId: string, projectId: string) { 'use cache'; // Missing cacheLife definition; defaults to platform defaults causing unpredictable SWR return db.query.projects.findFirst({ where: (p, { eq, and }) => and(eq(p.orgId, orgId), eq(p.id, projectId)), }); } export async function updateProjectTitle(orgId: string, projectId: string, title: string) { 'use server'; // Non-transactional execution with global coarse tag invalidation before completion revalidateTag('projects'); await db.update(projects).set({ title }).where(eq(projects.id, projectId)); return { success: true }; } ``` #### Production Standard (Correct) > **Standard**: Declares explicit `cacheLife` intervals for stale, revalidate, and expire tolerances, attaching composite hierarchical cache tags. The Server Action strictly encapsulates database updates inside a durable transaction and awaits success before invoking granular `revalidateTag` calls, guaranteeing monotonic coherence across all geo-distributed edge POPs. ```typescript import { revalidateTag, unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'; import { db } from '@/server/db'; import { projects } from '@/server/db/schema'; import { eq, and } from 'drizzle-orm'; // PRODUCTION-GRADE: Scoped cache tags with explicit bounded cacheLife export async function getOrganizationProject(orgId: string, projectId: string) { 'use cache'; cacheLife({ stale: 300, // 5 minutes client cache revalidate: 60, // SWR revalidation threshold on edge CDN expire: 3600 // Evict after 1 hour of inactivity }); cacheTag(`org:${orgId}:project:${projectId}`, `org:${orgId}:projects`); const project = await db.query.projects.findFirst({ where: (p, { eq, and }) => and(eq(p.orgId, orgId), eq(p.id, projectId)), }); if (!project) throw new Error('PROJECT_NOT_FOUND'); return project; } export async function updateProjectTitle(orgId: string, projectId: string, newTitle: string) { 'use server'; // Enforce read-after-write monotonicity: write & commit before invalidation const updatedProject = await db.transaction(async (tx) => { const [updated] = await tx .update(projects) .set({ title: newTitle, updatedAt: new Date() }) .where(and(eq(projects.orgId, orgId), eq(projects.id, projectId))) .returning(); if (!updated) { throw new Error('PROJECT_NOT_FOUND_OR_UNAUTHORIZED'); } return updated; }); // Invalidate exact entity tag and collection tag sequentially after commit revalidateTag(`org:${orgId}:project:${projectId}`); revalidateTag(`org:${orgId}:projects`); return { success: true, data: updatedProject }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Monotonic Cache Life & Tag Invalidation Guardrail

Next.js 15 Monotonic Cache Life & Tag Invalidation Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict monotonic read-after-write consistency across Next.js 15 edge nodes and the Data Cache layer during distributed database mutations. Prevents stale-while-revalidate race conditions and cross-region cache drift by mandating deterministic cacheLife profiles, entity-scoped cacheTag strategies, and post-commit tag revalidation barriers. 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: Executing un-scoped revalidateTag calls before write durability or using ambient cacheLife settings that serve stale edge state post-mutation. 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	Executing un-scoped revalidateTag calls before write durability or using ambient cacheLife settings that serve stale edge state post-mutation.	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 await database transaction commits and primary replication acknowledgement before invoking `revalidateTag` in Server Actions or Route Handlers.

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.