Next.js 16 Cache Components for Marketing Sites

The Short Answer: What Are Next.js Cache Components?

Next.js Cache Components are an opt-in caching primitive in Next.js 16 that wraps any async function, component, or file in a "use cache" directive. The function becomes a cache boundary: its arguments form part of the cache key, its return value is stored as a cache entry, and every subsequent call with the same arguments skips the work and returns the cached value. For marketing sites, that means a CMS-driven homepage, blog listing, or pricing page can render once and serve every visitor after that from the cached shell instead of re-running the work on every request.

The model replaces the older unstable_cache wrapper and the implicit fetch caching that App Router shipped with originally. Cache Components are explicit, composable, and pair with Partial Prerendering (PPR) so a single page can be partly static and partly dynamic—static shell, dynamic personalization holes, all on the same URL.

Why Cache Components Matter for Marketing Sites

Marketing sites have an awkward shape. Most of the page is identical for every visitor—hero, navigation, testimonials, footer—but a sliver is personalized: a logged-in badge, a geolocation-aware CTA, a session-aware pricing toggle. Old caching models forced you to choose: cache the whole page and ditch personalization, or render dynamically and pay the latency on every visit.

Cache Components break that tradeoff. The static parts cache; the dynamic parts stream. The user sees the cached shell instantly and the dynamic holes fill in over the same response—the same rendering model Vercel introduced as Partial Prerendering and folded into Cache Components in Next.js 16.

The performance math compounds with the rest of Next.js performance optimization—static shells are smaller, faster, and easier for the CDN to serve. They also pass Core Web Vitals more reliably because LCP candidates are typically in the cached shell, not the streamed holes.

The "use cache" Directive: Three Scopes

The directive is a string literal that mirrors the existing "use client" and "use server" conventions. Place it at the top of a file, function, or component to mark that scope as cacheable. Next.js builds a cache key from the function's arguments, then stores the result as a cache entry.

Turn On Cache Components First

"use cache", cacheLife, and cacheTag only do anything once the cacheComponents flag is set in your Next.js config. It's the single switch that replaces the old, separate experimental.dynamicIO and experimental.ppr flags from earlier Next.js versions.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

File Scope: Cache Every Export

Place "use cache" at the top of a file and every async export becomes a cache boundary. Useful for data layers where every query should cache by default.

'use cache'

import { cacheLife, cacheTag } from 'next/cache'
import { db } from '@/lib/db'

export async function getPost(slug: string) {
  cacheLife('hours')
  cacheTag(`post:${slug}`)
  return db.post.findUnique({ where: { slug } })
}

export async function listPosts() {
  cacheLife('hours')
  cacheTag('posts:list')
  return db.post.findMany({ orderBy: { date: 'desc' } })
}

Function Scope: Cache One Async Function

Place "use cache" inside a function to scope caching to that single call site. This is the most common pattern—you cache the expensive call but leave neighboring functions uncached.

async function getHomepageContent() {
  'use cache'
  cacheLife('hours')
  cacheTag('homepage')
  return await sanity.fetch(homepageQuery)
}

export default async function HomePage() {
  const content = await getHomepageContent()
  return <Hero {...content.hero} />
}

Component Scope: Cache an Async Server Component

Mark an async Server Component itself as cacheable. The component's rendered output—not just the data—is stored in the cache. Pair this with PPR and the cached component becomes part of the static prerender.

import { cacheLife, cacheTag } from 'next/cache'

async function PricingTable({ region }: { region: string }) {
  'use cache'
  cacheLife('hours')
  cacheTag(`pricing:${region}`)

  const tiers = await getPricing(region)
  return (
    <div className="grid md:grid-cols-3 gap-6">
      {tiers.map(t => <Tier key={t.id} {...t} />)}
    </div>
  )
}

export default function PricingPage() {
  return <PricingTable region="us" />
}

cacheLife: Tuning Freshness Windows

cacheLife controls three windows: how long a cached value stays fresh, how long it can be served as stale-while-revalidating, and when it should be evicted entirely. The function ships with named profiles that match common content cadences, plus a custom object form for fine-grained control.

For most marketing surfaces, the named profiles are enough. Reach for the custom object only when the named profiles don't fit—a daily-updated stat ticker, a rate-limited third-party API, or a regulated content type with explicit freshness requirements.

Custom cacheLife Object

async function getDailyReport() {
  'use cache'
  cacheLife({
    stale: 60 * 60,        // 1 hour stale window on the client
    revalidate: 60 * 30,   // revalidate every 30 minutes server-side
    expire: 60 * 60 * 24,  // hard evict after 24 hours
  })
  return fetchReport()
}

The three windows interact: a request inside the revalidate window returns the cached copy untouched; a request between revalidate and stale returns the cached copy and triggers a background refresh; a request past stale waits for a fresh fetch; a request past expire forces a full re-execution with no fallback.

cacheTag and updateTag: On-Demand Invalidation

Time-based revalidation works fine for content that changes on a predictable cadence, but most marketing sites need event-based invalidation. A writer publishes a post, an admin updates pricing, a webhook fires from the CMS—and the cache should clear immediately, not wait for the next revalidate window.

cacheTag attaches one or more string labels to a cached value. To invalidate every cached value carrying that label, call revalidateTag from a Server Action or a Route Handler (as of Next.js 16 it takes a required second argument—a cacheLife profile like "max"—for stale-while-revalidate behavior), or call updateTag from inside a Server Action when you need the very next read to reflect the change immediately. updateTag only works in Server Actions; a Route Handler like a CMS webhook must use revalidateTag.

// app/api/sanity/webhook/route.ts
import { revalidateTag } from 'next/cache'
import { NextResponse } from 'next/server'

export async function POST(req: Request) {
  const body = await req.json()
  const { type, slug } = body

  if (type === 'post') {
    revalidateTag(`post:${slug}`, 'max')
    revalidateTag('posts:list', 'max')
  }

  if (type === 'page') {
    revalidateTag(`page:${slug}`, 'max')
  }

  return NextResponse.json({ revalidated: true })
}

Source: Next.js docs—updateTag states it "can only be called from within Server Actions. It cannot be used in Route Handlers, Client Components, or any other context." Route Handlers and webhooks should use revalidateTag instead.

Tagging Strategies for Marketing Sites

• Per-entity tags: post:hello-world, page:pricing—invalidate one piece of content.
• Collection tags: posts:list, products:featured—invalidate listing pages when any item changes.
• Type tags: cms:all—nuclear option, useful for schema migrations.
• Region tags: pricing:us, pricing:eu—invalidate one geo without touching others.
• Combination tags: apply multiple tags to a single cache so one entry can be invalidated from several angles.

Pairing Cache Components with Partial Prerendering

Partial Prerendering (PPR) is the rendering model that pairs a cached static shell with streamed dynamic holes on the same route. In Next.js 16, PPR isn't a separate feature you switch on—it's built into Cache Components. Cache Components define the cached parts; Suspense boundaries define the dynamic parts. The cached shell ships as static HTML, and the dynamic holes stream in as the request resolves.

There's only one flag to set: cacheComponents: true in next.config.ts. The older experimental.ppr config option and the per-route export const experimental_ppr flag were both removed in Next.js 16 (nextjs.org/blog/next-16). If you're upgrading a project that still has the old per-route export, run npx @next/codemod@latest remove-experimental-ppr . to strip it before enabling cacheComponents. With cacheComponents on, anything you mark "use cache" is part of the shell, and anything you wrap in <Suspense> becomes a streamed, dynamic hole.

// next.config.ts
const nextConfig = {
  cacheComponents: true,
}
export default nextConfig

// app/page.tsx
export default function HomePage() {
  return (
    <>
      <Hero />              {/* cached, static */}
      <FeaturesGrid />      {/* cached, static */}
      <Suspense fallback={<UserBadgeSkeleton />}>
        <UserBadge />       {/* dynamic, streamed */}
      </Suspense>
      <Testimonials />      {/* cached, static */}
      <Suspense fallback={<RecentSignupsSkeleton />}>
        <RecentSignups />   {/* dynamic, streamed */}
      </Suspense>
      <Footer />            {/* cached, static */}
    </>
  )
}

The result: the shell serves from cache on every request, LCP candidates render from that prerendered shell instead of waiting on request-time work, and only the personalized fragments wait on dynamic data. Website speed optimization stops being a tradeoff with personalization—you get both.

Migrating from unstable_cache to Cache Components

Most App Router apps still use unstable_cache—the wrapper-style API that took a fetcher, options object with tags and revalidate, and returned a memoized version. Cache Components replace it cleanly. The migration is mechanical and can be done one function at a time.

Step-by-Step Migration

1. Locate every unstable_cache call site. Most are in lib/data or app/api directories.
2. Replace the wrapper with the directive. Add "use cache" at the top of the function and remove the unstable_cache wrapper.
3. Convert tags to cacheTag calls. Each tag string becomes a cacheTag(string) call inside the function.
4. Convert revalidate options to cacheLife. Pick a named profile or pass a custom object with the same revalidate seconds.
5. Give revalidateTag its new second argument, or switch to updateTag. A bare revalidateTag(tag) call now needs a cacheLife profile—revalidateTag(tag, 'max')—if it runs in a Route Handler or you want stale-while-revalidate behavior. If the call is inside a Server Action and you need the user's next read to reflect their own change immediately, use updateTag(tag) instead; it only works in Server Actions.
6. Test cache key behavior. Cache Components hash the function arguments; ensure no closures over external state are baked into the key.

import { unstable_cache } from 'next/cache'

export const getPost = unstable_cache(
  async (slug: string) => db.post.findUnique({ where: { slug } }),
  ['post'],
  { tags: ['posts'], revalidate: 3600 }
)

import { cacheLife, cacheTag } from 'next/cache'

export async function getPost(slug: string) {
  'use cache'
  cacheLife('hours')
  cacheTag(`post:${slug}`)
  return db.post.findUnique({ where: { slug } })
}

Real-World Patterns for Marketing Sites

Pattern 1: CMS-Driven Pages with Webhook Invalidation

The classic marketing setup: Sanity, Contentful, or Storyblok feeds the page, a webhook fires on publish, the cache clears. Cache Components make this five lines.

• Tag every page query with page:{slug} and a global cms:all fallback.
• Set cacheLife('days') since the webhook handles freshness.
• Webhook calls revalidateTag('page:{slug}', 'max') on publish, revalidateTag('cms:all', 'max') on schema migration—webhooks run in a Route Handler, so revalidateTag is the one that works there.
• Authoring teams see updates within seconds; visitors get edge-cached responses the rest of the time.

Pattern 2: Pricing Page with Geo-Aware Tiers

Price the same product differently by region without losing the static-shell speed. Cache the tier table per region, render the geo-detected wrapper dynamically inside a Suspense boundary.

async function PricingTiers({ region }: { region: string }) {
  'use cache'
  cacheLife('days')
  cacheTag(`pricing:${region}`)
  const tiers = await db.pricing.findMany({ where: { region } })
  return <TierGrid tiers={tiers} />
}

async function GeoPricing() {
  const country = (await headers()).get('x-vercel-ip-country') ?? 'us'
  const region = country === 'GB' ? 'eu' : country.toLowerCase()
  return <PricingTiers region={region} />
}

export default function PricingPage() {
  return (
    <Suspense fallback={<PricingSkeleton />}>
      <GeoPricing />
    </Suspense>
  )
}

Pattern 3: Blog Index with Featured Filtering

Blog listings have a long-tail problem: the index page is hit constantly, but the underlying data only changes when posts publish. Cache the listing query, tag it with the collection name, invalidate via webhook on every publish.

Pattern 4: Static Hero with Dynamic Personalization Hole

The marketing pattern Cache Components were built for. The hero, navigation, testimonials, and footer cache for hours. A single dynamic hole renders a logged-in CTA, an in-trial banner, or a regional offer, streamed through a Suspense boundary. Comparing Next.js vs Astro for marketing sites usually comes down to whether you need this dynamic-hole flexibility—Cache Components make Next.js the cleaner answer when you do.

Gotchas to Watch For After Deploy

Cache Components are clean in theory and mostly clean in practice. The few patterns that bite show up after deploy, not in development—local dev rebuilds bypass most of the caching infrastructure.

Closures Over External State

Cache keys hash function arguments, not closure variables. If a cached function reads from a module-level variable, the variable's value at first call is what gets baked into the cached output—forever, until cacheLife evicts. Pass everything you need as arguments.

Dynamic APIs Inside Cached Functions

cookies(), headers(), and searchParams() are dynamic by definition. Calling them inside a "use cache" function will throw a build error. If you need the value, pass it in as an argument from a non-cached parent.

Tag Explosion

It's tempting to tag every cached value with five tags. Don't. Each tag costs lookup time on invalidation, and Next.js itself caps a single cacheTag() call at 128 tags of up to 256 characters each—tags past the 128th are dropped and oversized tags are skipped, both with a console warning (Next.js docs—cacheTag limits, fetched 2026-09-28). Tag at most three layers: per-entity, per-collection, type-wide.

Revalidate Storms

A popular page with a short cacheLife and high traffic can trigger thousands of simultaneous revalidations the moment its window expires. Use the stale window aggressively—stale-while-revalidating means one request triggers the refresh while everyone else gets the cached copy. cacheLife profiles ship with sensible stale windows; resist shrinking them.

When to Cache (and When Not To)

Caching has a cost: cache key computation, storage, invalidation logic, and the cognitive load of reasoning about freshness. Not every function deserves "use cache". Here's the decision rubric we use on Verlua client builds.

The default stance: cache the data layer aggressively, leave UI components uncached unless they're demonstrably slow. For most marketing sites, caching the CMS query layer alone captures the bulk of the win—most of a marketing page's render time is the data fetch, not the rendering itself.

7-Day Cache Components Adoption Plan

If you're still on the App Router's implicit fetch caching or you're running an older framework choice, the broader question is whether React vs Next.js is even the right framework for the job. For data-heavy marketing sites with complex personalization, Next.js 16 with Cache Components is the strongest pick on the market right now.

Frequently Asked Questions