Next.js 15 'use cache' Cache-Tag Stale-While-Revalidate Boundary Guardrail

--- description: Next.js 15 'use cache' Cache-Tag Stale-While-Revalidate Boundary Guardrail - Enforces strict boundary isolation between transactional Server Action writes and edge-cached 'use cache' layout derivations in Next.js 15. Prevents stale read anomalies by requiring deterministic cache tagging, immediate post-mutation tag invalidation, and strict separation of transactional return payloads from eventual edge revalidation. globs: app/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-use-cache-tag-swr-boundary-guardrail" --- # Next.js 15 'use cache' Cache-Tag Stale-While-Revalidate Boundary Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Coupling Server Action Mutations to Un-invalidated 'use cache' Derivations with Inconsistent Read Replicas ## System Constraints You are a Principal Software Architect enforcing Next.js 15 'use cache' Cache-Tag Stale-While-Revalidate Boundary Guardrails. Mandate strict isolation between transactional write paths (Server Actions) and edge-cached read derivations ('use cache'). Enforce deterministic cache-tag naming, mandatory revalidation triggers, and prohibit reading cached layout functions within transactional write handlers. ## Strict Guidelines - Engineers MUST ALWAYS attach deterministic, domain-namespaced cache tags via 'cacheTag' inside any function or component declaring the 'use cache' directive. - Engineers MUST ALWAYS call 'revalidateTag' inside Server Actions immediately after a successful transactional mutation affecting tagged cached derivations. - Engineers MUST NOT invoke 'use cache' functions inside Server Actions or transactional mutation pipelines to verify write outcomes. - Services MUST return authoritative write payloads directly from Server Actions to the caller rather than forcing client components to rely on immediate edge cache re-reads. - Components NEVER combine user-session-specific state with coarse-grained global 'use cache' tags without including the tenant or user principal in the cache tag hierarchy. ## Bad vs Good Implementations ### Decoupled Server Action Mutation and 'use cache' Query with Tag Invalidation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The 'use cache' function lacks explicit cacheTag identification, making targeted invalidation impossible. The Server Action attempts to query the cached reader function immediately following a write, returning stale-while-revalidate edge data instead of transactional truth. ```typescript // Anti-pattern: Missing tag correlation and querying cached reads during mutation import { updateProjectName } from '@/lib/db'; export async function getProjects(tenantId: string) { 'use cache'; // Flaw: No deterministic cacheTag declared; implicit edge cache with indeterminate TTL const res = await fetch(`https://api.internal/tenants/${tenantId}/projects`); return res.json(); } export async function renameProjectAction(tenantId: string, projectId: string, name: string) { 'use server'; await updateProjectName(projectId, name); // Flaw: Fails to invalidate cache tags, returns stale data from cached reader const refreshed = await getProjects(tenantId); return { success: true, projects: refreshed }; } ``` #### Production Standard (Correct) > **Standard**: Binds the cached derivation to a deterministic cacheTag ('tenant:[id]:projects'). The Server Action executes the mutation against the system of record, explicitly revalidates the cache tag for background edge eviction, and returns the authoritative updated entity directly to avoid race conditions with asynchronous SWR propagation. ```typescript // Production standard: Strict tag-bound derivation with authoritative server action invalidation import { unstable_cacheTag as cacheTag, revalidateTag } from 'next/cache'; import { updateProjectNameInDb } from '@/lib/db'; import type { Project } from '@/types/project'; const PROJECT_TAGS = { byTenant: (tenantId: string) => `tenant:${tenantId}:projects` as const, byId: (projectId: string) => `project:${projectId}` as const, }; export async function getProjectsByTenant(tenantId: string): Promise<Project[]> { 'use cache'; cacheTag(PROJECT_TAGS.byTenant(tenantId)); const res = await fetch(`https://api.internal/tenants/${tenantId}/projects`, { headers: { 'X-Tenant-ID': tenantId }, }); if (!res.ok) throw new Error('Failed to resolve project derivations'); return res.json(); } export async function renameProjectAction( tenantId: string, projectId: string, name: string ): Promise<{ success: true; data: Project }> { 'use server'; const updatedProject = await updateProjectNameInDb(projectId, name); // Purge edge SWR cache across all regional nodes revalidateTag(PROJECT_TAGS.byTenant(tenantId)); revalidateTag(PROJECT_TAGS.byId(projectId)); // Return authoritative mutation record directly return { success: true, data: updatedProject }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 'use cache' Cache-Tag Stale-While-Revalidate Boundary Guardrail

Next.js 15 'use cache' Cache-Tag Stale-While-Revalidate Boundary Guardrail defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary isolation between transactional Server Action writes and edge-cached 'use cache' layout derivations in Next.js 15. Prevents stale read anomalies by requiring deterministic cache tagging, immediate post-mutation tag invalidation, and strict separation of transactional return payloads from eventual edge revalidation. 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: Coupling Server Action Mutations to Un-invalidated 'use cache' Derivations with Inconsistent Read Replicas 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	Coupling Server Action Mutations to Un-invalidated 'use cache' Derivations with Inconsistent Read Replicas	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 attach deterministic, domain-namespaced cache tags via 'cacheTag' inside any function or component declaring the 'use cache' directive.

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.