Allow adapters to customize headers for fetch requests #14543

matthewp · 2025-10-14T17:58:50Z

Changes

Add runtimeConfig.internalFetchHeaders to AstroAdapter interface
Create astro:adapter-config/client virtual module
Update Actions, View Transitions, Server Islands, and Prefetch to use adapter headers
Implement Netlify skew protection with DEPLOY_ID header
Generate .netlify/v1/skew-protection.json configuration file
Add comprehensive test fixture for skew protection
Closes @astrojs/vercel skew protection doesn't work #14545

Testing

Fixture tests added
Test project
- Repo: https://github.com/withastro/astro-netlify-skew-protection
- Prod app: https://skew-protection-test.netlify.app/

Docs

Document skew protection in Netlify adapter docs#12554

…otection) Adds a new generic mechanism for adapters to inject headers into Astro's internal fetch calls. This enables features like Netlify's skew protection. Changes: - Add `runtimeConfig.internalFetchHeaders` to AstroAdapter interface - Create `astro:adapter-config/client` virtual module - Update Actions, View Transitions, Server Islands, and Prefetch to use adapter headers - Implement Netlify skew protection with DEPLOY_ID header - Generate `.netlify/v1/skew-protection.json` configuration file - Add comprehensive test fixture for skew protection

changeset-bot · 2025-10-14T17:58:56Z

🦋 Changeset detected

Latest commit: a0424b6

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

packages/integrations/netlify/test/functions/skew-protection.test.js

- Add type declarations for astro:adapter-config/client virtual module - Add manifest property to SSRResult interface - Fix Object.entries type assertions in prefetch and router - Add explicit return type to Netlify adapter's internalFetchHeaders function

Follow existing pattern of extracting specific fields from manifest rather than passing the entire manifest object to SSRResult. This matches how other fields like base, trailingSlash, and serverIslandNameMap are handled.

packages/astro/src/prefetch/index.ts

codspeed-hq · 2025-10-14T18:25:35Z

CodSpeed Performance Report

Merging #14543 will not alter performance

_{Comparing netlify-skew-protection (a0424b6) with main (63b2568)}

Summary

✅ 6 untouched

- Remove incomplete test stubs for actions and view transitions - Remove unused manifestPath variable - Update prefetch comment to be less strict about dependencies

The test was checking ssr.mjs which is just a wrapper, but the actual serialized manifest is in the manifest_*.mjs file in the build directory.

This prevents timeouts in integration tests where client-side files importing the virtual module are processed during SSR.

pkg-pr-new · 2025-10-14T20:57:49Z

npm i https://pkg.pr.new/astro@14543

npm i https://pkg.pr.new/@astrojs/netlify@14543

commit: 4e36b0d

florian-lefebvre · 2025-10-15T08:04:06Z

Is the virtual module meant to be exposed to users or is it purely internal?

ematipico

The feature has a mixture of "client" and "runtime" concepts that seem to overlap, however we know that they are two different things.

I think we should normalise the nomenclature in our code and docs

packages/astro/src/types/public/integrations.ts

packages/astro/src/vite-plugin-adapter-config/index.ts

matthewp · 2025-10-15T15:01:14Z

@florian-lefebvre

Is the virtual module meant to be exposed to users or is it purely internal?

It's more or less internal. I thought about making it exposed to the user so they could use it in their own fetch calls but using the DEPLOY_ID in your own fetch calls is already easy enough.

ascorbic · 2025-10-17T17:18:42Z

.changeset/netlify-assetqueryparams.md

+Adds support for `assetQueryParams` and `internalFetchHeaders` in the Netlify adapter. When deployed to Netlify, the adapter now:
+
+- Includes the deployment ID in asset URLs via `assetQueryParams` (query parameter: `dpl`)
+- Includes the deployment ID in internal fetch requests via `internalFetchHeaders` (header: `X-Netlify-Deploy-ID`)
+
+This enables Netlify's skew protection feature, which ensures that client and server versions match during deployments by tracking the deployment ID across both asset requests and internal API calls.


This is mostly implementation detail. I'd lead on the fact this adds support for skew protection, and then say that it adds the query params and fetch headers. Users don't care about which adapter API it uses.

.changeset/vercel-fixes.md

packages/integrations/vercel/src/index.ts

sarah11918

OK, so this changed since I approved! 😄

Some suggestions, that I think somewhat addresses @ascorbic 's feedback!

.changeset/astro-asset-query-params.md

.changeset/netlify-assetqueryparams.md

.changeset/vercel-fixes.md

ascorbic

The Netlify team said that the feature could do with having a config option, but make it on by default. The Vercel one is off by default. I wonder if we should align them: both on by default but with an opt-out.

packages/astro/src/vite-plugin-adapter-config/client.d.ts

Co-authored-by: Sarah Rainsberger <[email protected]>

…into netlify-skew-protection

matthewp · 2025-10-20T12:47:00Z

@ascorbic Their suggestion was out of caution. I'd rather not add flag without knowing a use-case for it. If people complain for some reason we can add a flag later.

I've moved the Vercel implementation to use the VERCEL_SKEW_PROTECTION_ENABLED env as suggested, so it will be on by default. Can remove its option later assuming people aren't using it.

packages/integrations/vercel/src/index.ts

Co-authored-by: Steven <[email protected]>

ascorbic · 2025-10-20T19:58:00Z

@matthewp I think that as it is a brand new feature on Netlify and users will probably not even know they're using it, it would be good to at least have a way to opt-out in case it breaks stuff.

matthewp · 2025-10-21T14:24:31Z

@ascorbic If it breaks stuff they can downgrade the package until we fix it. If we add a flag and it breaks stuff they still need to find out and then set the flag to false. Not any easier than just downgrading. If we have a flag we have to keep it until a major at least, whereas if there's no flag we can either just fix the bug or if we find there's a real use-case for disabling it we can then add said flag.

sarah11918

Just making it extra clear that docs is again approving the newest version of the changesets!

Docs PR content is also approved, and will be good to go! (Just fiddling with larger changes the newer content is causing in other pages like changed anchor links)

Merge day

github-actions bot added pkg: integration Related to any renderer integration (scope) pkg: astro Related to the core `astro` package (scope) docs pr semver: minor Change triggers a `minor` release labels Oct 14, 2025

github-actions bot previously requested changes Oct 14, 2025

View reviewed changes

matthewp commented Oct 14, 2025

View reviewed changes

packages/integrations/netlify/test/functions/skew-protection.test.js Outdated Show resolved Hide resolved

matthewp commented Oct 14, 2025

View reviewed changes

packages/integrations/netlify/test/functions/skew-protection.test.js Outdated Show resolved Hide resolved

matthewp added 2 commits October 14, 2025 11:12

matthewp commented Oct 14, 2025

View reviewed changes

packages/astro/src/prefetch/index.ts Outdated Show resolved Hide resolved

matthewp added 4 commits October 14, 2025 11:28

Address PR feedback: clean up tests and update comment

abaa04f

- Remove incomplete test stubs for actions and view transitions - Remove unused manifestPath variable - Update prefetch comment to be less strict about dependencies

Fix import sorting in create-vite and router files

ea52496

Fix skew protection test to check correct manifest file

152298a

The test was checking ssr.mjs which is just a wrapper, but the actual serialized manifest is in the manifest_*.mjs file in the build directory.

Fix virtual module to return empty headers during SSR

a33869a

This prevents timeouts in integration tests where client-side files importing the virtual module are processed during SSR.

matthewp added this to the v5.15.0 milestone Oct 14, 2025

Merge branch 'main' into netlify-skew-protection

4e36b0d

matthewp mentioned this pull request Oct 14, 2025

Document skew protection in Netlify adapter withastro/docs#12554

Merged

matthewp marked this pull request as ready for review October 14, 2025 20:56

matthewp marked this pull request as draft October 14, 2025 20:56

matthewp added the pr preview Apply this label to a PR to generate a preview release label Oct 14, 2025

github-actions bot removed the pr preview Apply this label to a PR to generate a preview release label Oct 14, 2025

matthewp marked this pull request as ready for review October 14, 2025 21:44

ematipico reviewed Oct 15, 2025

View reviewed changes

packages/astro/src/types/public/integrations.ts Outdated Show resolved Hide resolved

packages/astro/src/types/public/integrations.ts Show resolved Hide resolved

packages/astro/src/vite-plugin-adapter-config/index.ts Outdated Show resolved Hide resolved

matthewp self-assigned this Oct 15, 2025

switch to use URLSearchParams

805cecc

ascorbic reviewed Oct 17, 2025

View reviewed changes

.changeset/vercel-fixes.md Outdated Show resolved Hide resolved

styfle reviewed Oct 17, 2025

View reviewed changes

packages/integrations/vercel/src/index.ts Outdated Show resolved Hide resolved

sarah11918 reviewed Oct 18, 2025

View reviewed changes

.changeset/astro-asset-query-params.md Outdated Show resolved Hide resolved

.changeset/astro-asset-query-params.md Outdated Show resolved Hide resolved

.changeset/netlify-assetqueryparams.md Outdated Show resolved Hide resolved

.changeset/vercel-fixes.md Outdated Show resolved Hide resolved

ascorbic reviewed Oct 18, 2025

View reviewed changes

florian-lefebvre reviewed Oct 20, 2025

View reviewed changes

packages/astro/src/vite-plugin-adapter-config/client.d.ts Outdated Show resolved Hide resolved

matthewp and others added 7 commits October 20, 2025 08:23

remove unneeded file

f131229

align vercel impl with how the other works

24cbfe7

focus changesets a bit more

2c623ba

Update .changeset/astro-asset-query-params.md

f515ff0

Co-authored-by: Sarah Rainsberger <[email protected]>

Update .changeset/astro-asset-query-params.md

da67fea

Co-authored-by: Sarah Rainsberger <[email protected]>

explain how to do it yourself too

f77ee2b

Merge branch 'netlify-skew-protection' of github.com:withastro/astro …

4639d13

…into netlify-skew-protection

oops

8490920

styfle reviewed Oct 20, 2025

View reviewed changes

packages/integrations/vercel/src/index.ts Outdated Show resolved Hide resolved

Update packages/integrations/vercel/src/index.ts

aa361ef

Co-authored-by: Steven <[email protected]>

Merge branch 'main' into netlify-skew-protection

a0424b6

sarah11918 approved these changes Oct 22, 2025

View reviewed changes

matthewp merged commit 9b3241d into main Oct 22, 2025
37 of 40 checks passed

matthewp deleted the netlify-skew-protection branch October 22, 2025 13:44

astrobot-houston mentioned this pull request Oct 22, 2025

[ci] release #14603

Merged

claude bot mentioned this pull request Oct 31, 2025

Update dependency astro to v5.15.6 - autoclosed RevolutionVA/757-community-site-public#151

Closed

1 task

ArmandPhilippot mentioned this pull request Nov 5, 2025

refactor(adapter-reference): improve adapter API docs withastro/docs#12673

Merged

teemingc mentioned this pull request Nov 20, 2025

fix: use query params for skew protection instead of cookies sveltejs/kit#14944

Draft

6 tasks

claude bot mentioned this pull request Dec 10, 2025

chore(deps): update astro monorepo rikuson/rikuson#203

Open

1 task

Uh oh!

Allow adapters to customize headers for fetch requests #14543

Allow adapters to customize headers for fetch requests #14543

Uh oh!

Conversation

matthewp commented Oct 14, 2025 • edited by florian-lefebvre Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Docs

Uh oh!

changeset-bot bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codspeed-hq bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #14543 will not alter performance

Summary

Uh oh!

pkg-pr-new bot commented Oct 14, 2025

Uh oh!

florian-lefebvre commented Oct 15, 2025

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matthewp commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ascorbic Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ascorbic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

matthewp commented Oct 20, 2025

Uh oh!

Uh oh!

ascorbic commented Oct 20, 2025

Uh oh!

matthewp commented Oct 21, 2025

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

matthewp commented Oct 14, 2025 •

edited by florian-lefebvre

Loading

changeset-bot bot commented Oct 14, 2025 •

edited

Loading

codspeed-hq bot commented Oct 14, 2025 •

edited

Loading

matthewp commented Oct 15, 2025 •

edited

Loading