A Next.js 16 Cache Components tutorial that threads tenant identity through every `'use cache'` cache key. Pass the tenant id as an explicit argument so it joins the key, tag each entry with `tenant:{id}` for surgical invalidation, and pick a `cacheLife` profile per tier. Runnable on Next.js 16.2.6. ## What you'll learn - Why Next.js bans `cookies()` / `headers()` / `searchParams` inside `'use cache'` and what the docs say happens to non-serializable closures[^use-cache-constraints]. - How to enable Cache Components in `next.config.ts` and use `'use cache'`, `cacheLife`, and `cacheTag` together[^cache-components]. - How to derive a per-tenant cache key from a route segment and propagate it through your data layer. - How to invalidate only one tenant's entries with `revalidateTag` and `updateTag`[^revalidate-vs-update]. - How to define a custom `cacheLife` profile in `next.config.ts` for a `pro` tenant tier with tighter freshness[^cache-life-config]. - How to verify cache hits and tenant scoping with `NEXT_PRIVATE_DEBUG_CACHE=1`[^debug-cache]. ## Prerequisites - Node.js 24.x. Node 24 is the current Active LTS through 20 Oct 2026 and then enters Maintenance LTS through 30 Apr 2028[^node-lts]. Next.js 16's engines field requires Node `>=20.9.0`, but Node 20 reached end-of-life on 30 Apr 2026[^node-lts], so do not start a new project on it[^next-engines]. - `pnpm` 10.x or `npm` 11.x. Examples use `pnpm`; swap to your manager freely. - A clean working folder for `pnpm dlx create-next-app@16.2.6 ...`. - Comfort with the App Router and Server Components. ## Why tenant-scoped cache keys matter Cache Components is opt-in caching. The `'use cache'` directive marks a function or component as cacheable; Next.js builds a cache key from the build id, a stable function id, the serialized arguments, and any **closure-captured variables**[^cache-keys]. Two calls with the same arguments share a cache entry. That is exactly what you want for shared marketing copy. It is exactly what you do not want for `getInvoices()` in a SaaS where every tenant has its own ledger. The danger is subtle. If your data-layer function takes no arguments, has no closure over a request-scoped value, and reads the tenant id from a module-level singleton or a side-channel, every tenant collapses into a single cache entry and the first request wins. Next.js explicitly disallows reading `cookies()`, `headers()`, or `searchParams` inside a `'use cache'` function precisely because the cache key cannot reflect their values[^use-cache-constraints]. The fix is to make tenant identity an **argument** to every cached function, then derive that argument from a place Next.js can see — the URL. ## Step 1 — Scaffold a Next.js 16 app with Cache Components Create the project interactively: ```bash pnpm dlx create-next-app@16.2.6 saas-cache --yes \ --ts --app --tailwind --src-dir --eslint \ --import-alias '@/*' cd saas-cache ``` Confirm the version that landed: ```bash pnpm list next # next 16.2.6 ``` Then enable Cache Components in `next.config.ts`: ```ts // next.config.ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { cacheComponents: true, } export default nextConfig ``` `cacheComponents` is the single flag that turns on `'use cache'`, `cacheLife`, and `cacheTag` together. It also enables Partial Prerendering as the default, so the static shell is served immediately while dynamic holes stream in[^cache-components]. ## Step 2 — Put the tenant id in the URL The cleanest way to thread tenant identity through a Next.js 16 app is a dynamic route segment, because route params are serializable, statically analyzable, and naturally flow as arguments. Create the directory tree: ``` src/app/ t/ [tenant]/ invoices/ page.tsx actions.ts src/lib/ invoices.ts tenants.ts ``` `src/lib/tenants.ts` resolves a slug to a tier. Treat this as a stand-in for your real tenant directory: ```ts // src/lib/tenants.ts export type Tier = 'free' | 'pro' export interface Tenant { id: string tier: Tier } const DIRECTORY: Record = { acme: { id: 'acme', tier: 'pro' }, globex: { id: 'globex', tier: 'free' }, } export function resolveTenant(slug: string): Tenant | null { return DIRECTORY[slug] ?? null } ``` `src/lib/invoices.ts` is the data layer. Notice every function takes `tenantId` as an explicit argument: ```ts // src/lib/invoices.ts import 'server-only' export interface Invoice { id: string tenantId: string amountCents: number paidAt: string | null } // Replace with your real Postgres/Drizzle/Prisma read. export async function fetchInvoicesFromDB( tenantId: string, ): Promise { const seed = tenantId.charCodeAt(0) return Array.from({ length: 3 }, (_, i) => ({ id: `${tenantId}-${i}`, tenantId, amountCents: (seed + i) * 1000, paidAt: i === 0 ? new Date().toISOString() : null, })) } ``` `'server-only'` causes the build to fail if anyone imports this file from a Client Component, keeping the data layer off the wire. The explicit `tenantId` argument is the separate guarantee that the cache key actually reflects which tenant asked. ## Step 3 — Cache with the tenant id as an argument Now the centerpiece. The cached read takes `tenantId` and calls `cacheTag` with a tenant-scoped tag, so the cache key includes the tenant and the invalidation surface is per-tenant: ```ts // src/lib/invoices.ts (continued) import { cacheLife, cacheTag } from 'next/cache' import type { Tier } from './tenants' export async function getInvoices( tenantId: string, tier: Tier, ): Promise { 'use cache' cacheTag(`tenant:${tenantId}`, `tenant:${tenantId}:invoices`) cacheLife(tier === 'pro' ? 'minutes' : 'hours') return fetchInvoicesFromDB(tenantId) } ``` Three things deserve attention here. **The arguments are the key.** Both `tenantId` and `tier` are part of the cache key because Next.js serializes function arguments into the key alongside the build id and the function's stable id[^cache-keys]. A `pro` tenant and a `free` tenant with the same id would land in separate entries, which is what you want because they have different freshness profiles. **Two tags, not one.** `tenant:acme` is the broad blast radius for a tenant-wide invalidation (a billing dispute, a tier change). `tenant:acme:invoices` is the surgical one used by the mutation in Step 5. Tag composition is cheap; tags are idempotent and capped at 256 characters per tag, 128 tags per entry[^cache-tag]. **`cacheLife` is called once per invocation.** The docs require exactly one `cacheLife` call per cached function invocation; resolving the profile name with a ternary keeps the call count to one regardless of tier[^cache-life]. Use it in the page: ```tsx // src/app/t/[tenant]/invoices/page.tsx import { notFound } from 'next/navigation' import { Suspense } from 'react' import { getInvoices } from '@/lib/invoices' import { resolveTenant } from '@/lib/tenants' export default async function InvoicesPage({ params, }: { params: Promise<{ tenant: string }> }) { const { tenant: slug } = await params const tenant = resolveTenant(slug) if (!tenant) notFound() return (

Invoices for {tenant.id}

Loading invoices…

) } async function InvoicesTable({ tenantId, tier, }: { tenantId: string tier: 'free' | 'pro' }) { const invoices = await getInvoices(tenantId, tier) return (

{inv.id} — ${(inv.amountCents / 100).toFixed(2)} {inv.paidAt ? ' (paid)' : ' (open)'}

) } ``` `params` is a `Promise` in Next.js 16, so it's awaited inside the Server Component. The `Suspense` boundary lets the surrounding markup render first and stream, while the cached table loads inside it on a cold cache. ## Step 4 — The anti-pattern Next.js refuses to compile The instinct that gets multi-tenant Cache Components wrong is to read the tenant from request-time storage **inside** the cached function: ```ts // src/lib/wrong-context.ts — DO NOT SHIP import { cookies } from 'next/headers' import { fetchInvoicesFromDB, type Invoice } from './invoices' export async function getInvoicesBroken(): Promise { 'use cache' // Build error: a "use cache" function cannot read cookies/headers/searchParams // because the cache key cannot reflect values that vary per request. const tenantId = (await cookies()).get('tenant')?.value ?? 'unknown' return fetchInvoicesFromDB(tenantId) } ``` Next.js disallows `cookies()`, `headers()`, and `searchParams` inside any `'use cache'` scope — exactly because a per-request value cannot legally participate in a key that is computed for reuse[^use-cache-constraints]. The error fires fast and is loud, which is the friendly version of the failure mode. The dangerous shape of the same mistake is a function whose closure-captured tenant value is non-serializable (a class instance, a function reference returned by an imported getter, a runtime-only object) — the docs note that non-serializable closed-over values "can be only passed through and not inspected nor modified" inside a cached function[^use-cache-constraints]. Treat any of these patterns as a refactor, not a workaround: read the tenant value **outside** the `'use cache'` boundary — from `params`, from a layout that already resolved it, from a server-side `cookies()` call up the stack — and pass it in as a plain string. That puts the tenant identity squarely in the cache key, which is what Step 3 does. ## Step 5 — Tenant-scoped invalidation with `updateTag` When a tenant pays an invoice, only that tenant's entry should refresh. `updateTag` works exclusively inside Server Actions and gives you read-your-own-writes semantics — the next request waits for fresh data rather than serving stale[^update-tag]: ```ts // src/app/t/[tenant]/invoices/actions.ts 'use server' import { updateTag } from 'next/cache' import { resolveTenant } from '@/lib/tenants' export async function markInvoicePaid( slug: string, invoiceId: string, ): Promise<{ ok: true } | { ok: false; error: string }> { const tenant = resolveTenant(slug) if (!tenant) return { ok: false, error: 'unknown tenant' } // Replace with the real UPDATE against your billing table. await new Promise((r) => setTimeout(r, 50)) // Only invalidate this tenant's invoice cache. updateTag(`tenant:${tenant.id}:invoices`) return { ok: true } } ``` Wire the action to a tiny form in the page: ```tsx // src/app/t/[tenant]/invoices/page.tsx (additions) import { markInvoicePaid } from './actions' // ...inside the Server Component, render this near the heading: ``` Two follow-on rules. First, `updateTag` throws if you call it outside a Server Action — the docs are explicit about this and call out Route Handlers and background tasks as forbidden contexts[^update-tag]. From a Route Handler webhook, use `revalidateTag(tag, 'max')` for stale-while-revalidate semantics instead[^revalidate-vs-update]. Second, on a multi-instance deployment, both functions are **local to one instance** by default; for cluster-wide invalidation you need a custom cache handler that writes to shared storage like Redis[^cache-handler]. ## Step 6 — A custom `cacheLife` profile for the `pro` tier The built-in profiles cover the common cases: `seconds` for live data, `minutes` for feeds, `hours` for inventory, `days` for blog content, `weeks`, and `max` for stable content. Each balances three timings — `stale` (client router), `revalidate` (background server refresh), `expire` (synchronous regeneration on next request after a quiet period)[^cache-life]. For a SaaS where the `pro` tier promises near-real-time invoicing but you still want a cache, override or extend with a custom profile in `next.config.ts`: ```ts // next.config.ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { cacheComponents: true, cacheLife: { proInvoices: { stale: 30, // 30s client cache; minimum 30s is enforced anyway revalidate: 60, // 1 min background refresh expire: 600, // 10 min hard expiry }, }, } export default nextConfig ``` Any property you omit inherits from the `default` profile, including the inline form `cacheLife({})`[^cache-life]. Reference the named profile in the data layer: ```ts // src/lib/invoices.ts (update) cacheLife(tier === 'pro' ? 'proInvoices' : 'hours') ``` The 30-second client minimum is enforced by the router so prefetched links stay clickable; do not try to go lower in the `stale` field[^cache-life]. The dynamic-hole rule is the other side to watch: any profile with `revalidate: 0` or `expire` under 5 minutes — including the built-in `seconds` profile — is excluded from prerenders and becomes a "dynamic hole" that must sit inside a `Suspense` boundary[^cache-life]. The `proInvoices` profile above (`expire: 600`) is comfortably above that threshold, so it stays eligible for prerendering on routes that are otherwise static. On the dynamic route in Step 3 the `Suspense` boundary still earns its keep on cold-cache loads, and it would become structurally required if you ever moved the table to `cacheLife('seconds')`. ## Verification Run the dev server with cache logging on: ```bash NEXT_PRIVATE_DEBUG_CACHE=1 pnpm dev ``` Hit each tenant and check that the response contains the right tenant's data: ```bash curl -s http://localhost:3000/t/acme/invoices | grep -c 'acme-0' # → 1 curl -s http://localhost:3000/t/globex/invoices | grep -c 'globex-0' # → 1 curl -s http://localhost:3000/t/acme/invoices | grep -c 'globex-0' # → 0 ``` The first two assertions are the ones that catch the cross-tenant leak: each tenant's page must render its own invoice ids. If the second command returns `0` instead of `1`, the globex page is serving acme's cached data — the cache key is tenant-blind, so re-read Step 4. The third assertion is the inverse check: an acme page should never contain a globex invoice. The dev console emits cached-function output with a `Cache` prefix and the `x-nextjs-stale-time` header on responses so you can watch what's being served from where[^debug-cache]. For build-time verification, run `pnpm build` and inspect the route table. Next.js marks statically prerendered routes with `○` and dynamic routes with `ƒ`[^build-symbols]. Because `/t/[tenant]/invoices` is a dynamic-param route with no `generateStaticParams`, it will show `ƒ` — that is expected, and Cache Components still streams the cached table inside `Suspense`. The second hit to the same tenant returns from the in-memory cache, which is what `NEXT_PRIVATE_DEBUG_CACHE=1` lets you watch in the dev console. ## Troubleshooting **`Error: Route used "cookies" inside "use cache"`** — you tried to read `cookies()`, `headers()`, or `searchParams` inside a cached function. Move the read above the `'use cache'` boundary and pass the value in as an argument[^use-cache-constraints]. If you genuinely cannot refactor, the `'use cache: private'` directive exists for that edge case but excludes the result from the prerender cache. **`Error: Filling a cache during prerender timed out`** — you passed an unresolved Promise that depends on runtime data into a cached function. Common causes: passing `cookies()` as a Promise prop, or pulling a runtime value out of a module-level `Map` from inside `'use cache'`. Read the runtime value in a dynamic component, then pass the resolved value to the cached one[^use-cache-constraints]. **`updateTag` throws "can only be called from within a Server Action"** — you called it from a Route Handler or a background job. From a Route Handler, use `revalidateTag(tag, 'max')` instead and accept stale-while-revalidate semantics[^update-tag]. **Tenant A still sees Tenant B's data after a mutation** — either you tagged with `'invoices'` instead of `tenant:${id}:invoices`, or your deployment is multi-instance and `updateTag`/`revalidateTag` ran on one instance only. Tag every entry with at least one tenant-scoped tag, and put a shared cache handler in front of the cluster[^cache-handler]. **`stale` lower than 30 in `cacheLife` does nothing on the client** — the client router enforces a 30-second minimum on `stale` so prefetched links don't expire mid-hover[^cache-life]. The server-side `revalidate` and `expire` remain whatever you set. ## Next steps - Replace `fetchInvoicesFromDB` with a real Drizzle or Prisma read inside a transaction. The [Drizzle ORM + pg-boss tutorial](/drizzle-orm-pg-boss-atomic-transactions-tutorial) shows the transactional pattern. - Add tenant-scoped streaming with [Next.js 16 Suspense + use cache](/nextjs-16-streaming-suspense-use-cache-tutorial) for richer dashboards. - For a self-hosted cluster, write a custom `cacheHandler` that bridges `updateTag`/`revalidateTag` to Redis so invalidation events cross instances. The pattern composes with the [API rate limiting with Upstash Redis sliding window](/api-rate-limiting-upstash-redis-sliding-window-tutorial) approach for the cluster's Redis dependency. [^cache-components]: Next.js docs, "cacheComponents" — https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents (lastUpdated 2026-05-31). [^cache-keys]: Next.js docs, "use cache — Cache keys" — https://nextjs.org/docs/app/api-reference/directives/use-cache (lastUpdated 2026-05-28). [^use-cache-constraints]: Next.js docs, "use cache — Constraints / Request-time APIs" — https://nextjs.org/docs/app/api-reference/directives/use-cache (lastUpdated 2026-05-28). [^cache-life]: Next.js docs, "cacheLife function" — https://nextjs.org/docs/app/api-reference/functions/cacheLife (lastUpdated 2026-05-13). [^cache-life-config]: Next.js docs, "cacheLife (next.config)" — https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheLife. [^cache-tag]: Next.js docs, "cacheTag function" — https://nextjs.org/docs/app/api-reference/functions/cacheTag (lastUpdated 2026-03-20). [^update-tag]: Next.js docs, "updateTag function" — https://nextjs.org/docs/app/api-reference/functions/updateTag (lastUpdated 2026-05-28). [^revalidate-vs-update]: Next.js docs, "revalidateTag function" — https://nextjs.org/docs/app/api-reference/functions/revalidateTag. [^cache-handler]: Next.js docs, "How Revalidation Works — Distributed coordination" — https://nextjs.org/docs/app/guides/how-revalidation-works. [^debug-cache]: Next.js docs, "use cache — Debugging cache behavior" — https://nextjs.org/docs/app/api-reference/directives/use-cache (lastUpdated 2026-05-28). [^next-engines]: `npm view next@16.2.6 engines` returns `{ node: '>=20.9.0' }` (verified 2026-06-01). [^node-lts]: endoflife.date, "Node.js" — https://endoflife.date/nodejs (last updated 22 May 2026). [^build-symbols]: Next.js docs, "devIndicators" + Automatic Static Optimization — https://nextjs.org/docs/app/api-reference/config/next-config-js/devIndicators. `○` denotes a statically prerendered route; `ƒ` denotes a dynamically rendered route.

#cache-components

Next.js 16 Cache Components: Multi-Tenant Tutorial (2026)