fix: preserve custom Vary headers

[Timer]

What?

Changes the handling of Vary headers in Next.js to preserve custom headers while properly appending required Next.js internal headers using appendHeader instead of setHeader.

Why?

To ensure custom Vary headers set by users are not overwritten when Next.js needs to add its own internal headers for features like RSC and routing. This maintains proper caching behavior while supporting user-defined variations.

How?

• Replaced setHeader with appendHeader for Vary headers in base-server.ts
• Added tests to verify custom Vary headers are preserved in both API routes and App Router handlers
• Ensures Next.js internal headers (RSC, Router State Tree, Router Prefetch) are properly appended

---

Fixes #48480
Fixes #55396

[Timer]

• fix: preserve custom Vary headers #75536 👈 (View in Graphite)
• canary

This stack of pull requests is managed by Graphite. Learn more about stacking.

[darthmaim]

This might fix:

• Cannot set Vary header in middleware #48480

A test case confirming this PR also works for Vary set in middleware would be good.

[ijjk]

Allow CI Workflow Run

• approve CI run for commit: c0f7a0c

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[ijjk]

Stats from current PR

Default Build (Increase detected ⚠️)

General Overall increase ⚠️

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
buildDuration	22.1s	20.2s	N/A
buildDurationCached	19.4s	16.9s	N/A
nodeModulesSize	391 MB	391 MB	⚠️ +2.67 kB
nextStartRea..uration (ms)	491ms	502ms	N/A

Client Bundles (main, webpack)

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
5306-HASH.js gzip	54 kB	53.9 kB	N/A
8276.HASH.js gzip	169 B	168 B	N/A
8377-HASH.js gzip	5.46 kB	5.46 kB	N/A
bccd1874-HASH.js gzip	52.9 kB	52.9 kB	N/A
framework-HASH.js gzip	57.5 kB	57.5 kB	N/A
main-app-HASH.js gzip	241 B	242 B	N/A
main-HASH.js gzip	34.5 kB	34.4 kB	N/A
webpack-HASH.js gzip	1.71 kB	1.71 kB	N/A
Overall change	0 B	0 B	✓

Legacy Client Bundles (polyfills)

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
polyfills-HASH.js gzip	39.4 kB	39.4 kB	✓
Overall change	39.4 kB	39.4 kB	✓

Client Pages

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
_app-HASH.js gzip	193 B	193 B	✓
_error-HASH.js gzip	193 B	193 B	✓
amp-HASH.js gzip	512 B	510 B	N/A
css-HASH.js gzip	343 B	342 B	N/A
dynamic-HASH.js gzip	1.84 kB	1.84 kB	✓
edge-ssr-HASH.js gzip	265 B	265 B	✓
head-HASH.js gzip	363 B	362 B	N/A
hooks-HASH.js gzip	393 B	392 B	N/A
image-HASH.js gzip	4.59 kB	4.58 kB	N/A
index-HASH.js gzip	268 B	268 B	✓
link-HASH.js gzip	2.35 kB	2.35 kB	N/A
routerDirect..HASH.js gzip	328 B	328 B	✓
script-HASH.js gzip	397 B	397 B	✓
withRouter-HASH.js gzip	323 B	326 B	N/A
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Overall change	3.59 kB	3.59 kB	✓

Client Build Manifests

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
_buildManifest.js gzip	748 B	747 B	N/A
Overall change	0 B	0 B	✓

Rendered Page Sizes

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
index.html gzip	523 B	524 B	N/A
link.html gzip	538 B	538 B	✓
withRouter.html gzip	519 B	520 B	N/A
Overall change	538 B	538 B	✓

Edge SSR bundle Size

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
edge-ssr.js gzip	129 kB	129 kB	N/A
page.js gzip	210 kB	210 kB	N/A
Overall change	0 B	0 B	✓

Middleware size

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
middleware-b..fest.js gzip	670 B	666 B	N/A
middleware-r..fest.js gzip	155 B	156 B	N/A
middleware.js gzip	31.3 kB	31.3 kB	N/A
edge-runtime..pack.js gzip	844 B	844 B	✓
Overall change	844 B	844 B	✓

Next Runtimes

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
app-page-exp...dev.js gzip	386 kB	386 kB	✓
app-page-exp..prod.js gzip	132 kB	132 kB	✓
app-page-tur..prod.js gzip	145 kB	145 kB	✓
app-page-tur..prod.js gzip	141 kB	141 kB	✓
app-page.run...dev.js gzip	373 kB	373 kB	✓
app-page.run..prod.js gzip	128 kB	128 kB	✓
app-route-ex...dev.js gzip	39.2 kB	39.2 kB	✓
app-route-ex..prod.js gzip	25.6 kB	25.6 kB	✓
app-route-tu..prod.js gzip	25.6 kB	25.6 kB	✓
app-route-tu..prod.js gzip	25.4 kB	25.4 kB	✓
app-route.ru...dev.js gzip	40.8 kB	40.8 kB	✓
app-route.ru..prod.js gzip	25.4 kB	25.4 kB	✓
dist_client_...dev.js gzip	356 B	356 B	✓
dist_client_...dev.js gzip	349 B	349 B	✓
pages-api-tu..prod.js gzip	9.69 kB	9.69 kB	✓
pages-api.ru...dev.js gzip	11.8 kB	11.8 kB	✓
pages-api.ru..prod.js gzip	9.68 kB	9.68 kB	✓
pages-turbo...prod.js gzip	21.9 kB	21.9 kB	✓
pages.runtim...dev.js gzip	31.5 kB	31.5 kB	✓
pages.runtim..prod.js gzip	21.9 kB	21.9 kB	✓
server.runti..prod.js gzip	60.2 kB	60.2 kB	N/A
Overall change	1.59 MB	1.59 MB	✓

build cache Overall increase ⚠️

	vercel/next.js canary	vercel/next.js Preserve_custom_Vary_headers_in_API_routes_and_app_handlers	Change
0.pack gzip	2.1 MB	2.1 MB	⚠️ +401 B
index.pack gzip	75.2 kB	74.5 kB	N/A
Overall change	2.1 MB	2.1 MB	⚠️ +401 B

Diff details

Diff for edge-ssr.js

Diff too large to display

Diff for main-HASH.js

Diff too large to display

Diff for server.runtime.prod.js

Diff too large to display

Commit: c0f7a0c

[Multiply]

Thank you! 🚀