Why does cache.varies not reflect in response headers while cache.maxAge does?

[Leon2xiaowu]

Hi Nitro team! 👋

I've been exploring Nitro's caching capabilities and noticed an inconsistency in how caching rules are exposed in HTTP responses:

1. cache.maxAge correctly sets the Cache-Control: max-age=X header (visible in responses). ✅
2. cache.varies (e.g., varies: ['cookie', 'accept-language']) does not generate a Vary header in responses. ❌

Expected Behavior:

When configuring route rules like:

routeRules: {
  '/profile': {
    cache: { 
      maxAge: 86400,
      varies: ['cookie', 'accept-language']
    }
  }
}

I expect the response to include:

Cache-Control: max-age=86400
Vary: Cookie, Accept-Language

Current Behavior:

Only Cache-Control is present; Vary is missing entirely.

Questions:

1. Is this intentional design? If so, what’s the rationale for omitting Vary?
2. If unintentional, could this be a bug or limitation?
3. Are there workarounds to manually inject Vary headers alongside cache.varies?

The Vary header is critical for correct cache behavior (e.g., when using CDNs or dynamic content). Its absence might lead to improper caching.

Thanks for your insights! 🙏

[sunnypatell]

@Leon2xiaowu this is by design. cache.varies controls which request headers are used to generate the internal cache key (server-side differentiation), not which headers appear in the HTTP response. it tells nitro's caching layer "create separate cache entries when these request headers differ."

cache.maxAge does double duty (sets both internal TTL and the Cache-Control response header), but varies is internal only.

to also set the Vary response header for CDN/browser caching, combine both options:

// nitro.config.ts
export default defineNitroConfig({
  routeRules: {
    '/profile': {
      cache: { maxAge: 86400, varies: ['cookie', 'accept-language'] },
      headers: { 'Vary': 'Cookie, Accept-Language' },
    },
  },
});

or use a middleware if you need more control:

// server/middleware/vary.ts
export default defineEventHandler((event) => {
  if (event.path.startsWith('/profile')) {
    setHeader(event, 'Vary', 'Cookie, Accept-Language');
  }
});

ref: nitro cache docs