Next.js 16 Cache Components Guide 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 the cache key, its return value lives in the Data Cache, 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 at the edge and serve thousands of visitors in single-digit milliseconds.

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. Vercel's PPR launch data showed median TTFB drops of 40–80% on representative marketing pages versus full dynamic rendering.

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 and return value, then stores the result in the Data Cache.

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. updateTag, called from a Server Action or route handler, invalidates every cached value carrying that label. The pattern is purpose-built for content workflows.

// app/api/sanity/webhook/route.ts
import { updateTag } 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') {
    updateTag(`post:${slug}`)
    updateTag('posts:list')
  }

  if (type === 'page') {
    updateTag(`page:${slug}`)
  }

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

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. Cache Components define the cached parts; Suspense boundaries define the dynamic parts. The cached shell ships from the CDN as static HTML, the dynamic holes stream in as the request resolves.

Enable PPR per route or globally with the experimental flag in next.config.js, then mark dynamic boundaries with <Suspense>. Anything outside a Suspense boundary that doesn't opt into dynamic APIs (cookies, headers, searchParams) becomes part of the cached shell.

// next.config.js
module.exports = {
  experimental: { ppr: 'incremental' },
}

// app/page.tsx
export const experimental_ppr = true

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: TTFB is the cached shell's TTFB (typically <100ms from edge), LCP candidates render from the static prerender, and only the personalized fragments wait on the dynamic work. 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. Replace revalidateTag with updateTag. The function signature is the same; only the import path and name change.
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 updateTag('page:{slug}') on publish, updateTag('cms:all') on schema migration.
• 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 the platform CDN has soft limits on tags per cache entry (Vercel's limit is documented at 64 tags per entry as of April 2026). 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. Most marketing sites get 80% of the wins from caching the CMS query layer alone.

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