Next.js Caching on Vercel: Safe Defaults for Public Content

Published

Jul 14, 2026

Updated

Jul 14, 2026

Reading time

10 min read

Caching on Vercel is not one switch. A Next.js application can cache a server-side fetch, prerender route output, and let Vercel's CDN cache a complete HTTP response. These are separate layers with separate invalidation behavior. This guide uses Acme Shop's public catalog; it does not cache its account, cart, checkout, or authenticated API responses.

Start with Acme Shop's cache boundary

The catalog is identical for all visitors and may be up to five minutes old. An account summary is not identical, even when two visitors request the same URL. Write that distinction down before adding a header or a tag.

The public response cache and the Next.js data cache can both reduce origin work, but a HIT at one layer is not proof of a hit at the other. Treat the output's privacy contract as the first cache key.

Cache the public catalog fetch explicitly

Next.js 16 does not cache fetch requests by default in this model. Make Acme Shop's intended persistence, freshness, and invalidation target explicit. force-cache permits persistent storage; revalidate limits its lifetime; the tag is reserved for narrow on-demand invalidation.

// lib/acme-shop/catalog.ts
export type Product = { slug: string; name: string; priceCents: number }

export async function getPublicCatalog(): Promise<Product[]> {
  const response = await fetch("https://catalog.acme-shop.example/v1/products", {
    cache: "force-cache",
    next: { revalidate: 300, tags: ["acme-shop:catalog"] },
  })

  if (!response.ok) throw new Error("Public catalog is unavailable")
  return response.json()
}

// app/shop/page.tsx
import { getPublicCatalog } from "@/lib/acme-shop/catalog"

export default async function ShopPage() {
  const products = await getPublicCatalog()
  return <ul>{products.map((product) => <li key={product.slug}>{product.name}</li>)}</ul>
}

revalidate: 300 is a maximum cache lifetime, not a guarantee that every region warms at the same moment. The smallest revalidation value used by a route can also lower that route's revalidation frequency.

Keep the private account path non-cacheable

Do not try to make a session token part of a shared cache key. Acme Shop fetches account data for the current visitor on every request.

// lib/acme-shop/account.ts
export async function getAccount(accessToken: string) {
  const response = await fetch("https://accounts.acme-shop.example/v1/me", {
    cache: "no-store",
    headers: { Authorization: `Bearer ${accessToken}` },
  })

  if (!response.ok) throw new Error("Account is unavailable")
  return response.json()
}

Reading cookies() or headers() does not make a shared response safe. Ensure the fetch policy, route behavior, and HTTP response headers all match the private-data requirement.

Cache one complete public response at the CDN

The data cache does not automatically make an entire HTTP response CDN-cacheable. For Acme Shop's public catalog API only, return a complete representation with a Vercel-specific TTL and a CDN tag. The browser receives the short browser policy; Vercel consumes Vercel-CDN-Cache-Control and removes Vercel-Cache-Tag before sending the response onward.

// app/api/public-catalog/route.ts
import { getPublicCatalog } from "@/lib/acme-shop/catalog"

export async function GET() {
  const products = await getPublicCatalog()

  return Response.json(
    { catalogRevision: "2026-07-14T10:00Z", products },
    {
      headers: {
        "Cache-Control": "public, max-age=0, must-revalidate",
        "Vercel-CDN-Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
        "Vercel-Cache-Tag": "acme-shop:catalog-response",
      },
    }
  )
}

Do not add these headers when the request carries Authorization, the response sets a cookie, output differs by visitor, or the body contains sensitive data. Those responses do not meet Vercel's CDN cacheability criteria.

HTTP/2 200
content-type: application/json
cache-control: public, max-age=0, must-revalidate
x-vercel-cache: HIT

{"catalogRevision":"2026-07-14T10:00Z","products":[{"slug":"solar-pack","name":"Solar Pack","priceCents":12900}]}

Validate public, private, and failure behavior

Deploy the reviewed change to a preview URL. For protected previews, vercel curl automatically handles deployment-protection bypass; it is currently a beta CLI command. For a public preview, ordinary curl is sufficient.

vercel curl /api/public-catalog --deployment https://acme-shop-preview.example
vercel curl /api/public-catalog --deployment https://acme-shop-preview.example
vercel httpstat /api/public-catalog --deployment https://acme-shop-preview.example

Vercel's CDN is regional. A warm result from one location is not proof that every region is warm. Save the URL, time, headers, body revision, and request location with the change record.

Recover without broad purges

If a public response is wrong, first remove the unsafe cache eligibility or restore the known-good deployment. Then verify the body and a signed-in journey. Only after the response is correct, invalidate the narrow public CDN tag through a reviewed, linked-project session:

vercel cache invalidate --tag acme-shop:catalog-response

For a wrong Next.js data-cache value, use the authenticated application revalidation workflow in the revalidation guide; a CDN invalidation does not repair bad source data or an unsafe route design. Avoid vercel cache purge as a first response because it is broader than this catalog change and can increase origin load.

Troubleshooting

Related guides

• Debug Next.js caching on Vercel
• Revalidate public Next.js data on Vercel

Authoritative references

• Next.js caching and revalidation
• Next.js fetch API reference
• Vercel CDN Cache
• Vercel Cache-Control headers