Next.js and Vary — why it’s currently impossible to cache variants “properly”

[Winfle]

Summary

TL;DR: In Next.js, simply calling headers()/cookies() during page/component render automatically marks the page as dynamic and sends it with private/no-store. This breaks proper Vary handling (locale, customer-group, etc.): we want a public cache with variability, but end up with completely uncacheable HTML.

What’s wrong

1. Optimization without consent – Any use of headers() or cookies() in RSC/SSR => Next disables full-page caching and sets private cache headers.
2. Public cache variants are not “client data” – If I read a header that only determines a public variant (e.g., accept-language), that’s not private per-user data. Developers should be able to explicitly mark that context as public-safe.
3. Breaks dynamic CDN integration – Without the ability to serve public HTML variants with Vary, we can’t leverage standard CDN behavior (Fastly, CloudFront) to handle edge caching efficiently.
4. No way to declare “I know what I’m doing, cache with Vary” – There’s no official mechanism to allow public + Vary: for HTML when render output legitimately depends on a header/cookie.

End result: HTML is never cached – We’re forced to push the variability into JSON/API responses instead of the page itself.

Why this is a problem
We have a valid need for public cache with variability (e.g., Vary: accept-language, x-customer-group). This is a standard HTTP mechanism and CDNs like Fastly handle it perfectly.

Forced anti-pattern: Move header reading to an API route, set Vary there, and keep the HTML “static.” This adds complexity, extra requests, lack and doesn’t work well when the layout truly depends on the variant.

I'm looking for a solution to mark cache as public with having variants in place.

Thanks

Additional information

No response

Example

Minimal code:

// app/page.tsx
import { headers } from 'next/headers';

export default async function Page() {
  const h = await headers();
  const locale = h.get('accept-language')?.split(',')[0] ?? 'en';
  return <main>Locale: {locale}</main>;
}
// Expected: public cache + Vary: accept-language
// Actual: dynamic page with private/no-store

[victormoni]

Hi @Winfle

It looks like the author is running into a core behavior of the Next.js App Router: as soon as you call headers() or cookies() in a Server Component (RSC/SSR), the framework marks the page as “dynamic” and sends it with Cache-Control: private, no-store. That means:

• You lose full-page public caching.

• The HTML can’t be cached by a CDN even if the only “dynamic” value is something that could be handled via Vary (e.g. accept-language).

• There’s no way today to explicitly say “I know this is safe to cache publicly with a Vary header.”

At the moment, there isn’t a built-in way to override this and keep public caching with HTML variants. If you truly need HTML to be cached with a Vary, the only supported workarounds are:

1. Move the header/cookie handling to an API route

• Render your page as static HTML.

• Use JavaScript on the client to call your API and fetch the variant-specific data.

• This keeps the HTML static (cacheable), but it means the variant logic happens client-side or via an extra request.

2. Use Edge Middleware for variant handling

• Middleware runs before the cache decision, and you can read headers there.

• You can then set Vary and route to different static assets based on the variant.

• This still has limits, because middleware itself doesn’t make the HTML dynamic — it selects which static variant to serve.

3. Pre-generate variants as separate static paths

• If the set of variants is small (e.g. languages), you can prebuild /en, /fr, etc.

• Then detect in middleware and redirect to the appropriate static variant.

• CDNs will happily cache each variant independently.

Unfortunately, there’s no public API in Next.js 13/14 that lets you call headers()/cookies() in a page and still tell the framework “this is public cacheable HTML with Vary” — the team would need to add an opt-in, like setCache({ mode: 'public', vary: ['accept-language'] }).

If you want this to change, the best path is to:

• Open or upvote an RFC in the Next.js repo proposing an explicit public-cache mode with Vary support.

• Provide your use-case (like you did here) to help the maintainers prioritize.