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

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: 4e36b0d

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 (4e36b0d) with main (62ec8ea)¹}

Summary

✅ 6 untouched

No successful run was found on main (6d68316) during the generation of this report, so 62ec8ea was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

- 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

ematipico · 2025-10-15T08:29:39Z

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

+	/**
+	 * Runtime configuration that will be available to Astro's client-side code.
+	 */
+	runtimeConfig?: {


We are already inside a configuration, so calling this Config seems redundant.

Also, "runtime" and client-side code have different meanings to us, so I would look for a better name or a better description.

Sure, what would you recommend? Below you recommended /runtime for the virtual module, so I think runtime here would be nice for symmetry. Sound good?

Yeah, as long as we align the terms, I don't have strong opinions. But I think client is a better fit, because runtime is also code that runs on the server, which isn't the case.

Regardless, it's just a suggestion, as long as the docs and names are aligned, I'm good :)

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

ematipico · 2025-10-15T08:36:14Z

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

+import type { Plugin as VitePlugin } from 'vite';
+import type { AstroSettings } from '../types/astro.js';
+
+const VIRTUAL_CLIENT_ID = 'astro:adapter-config/client';


The presence of /client implies a possible /server. However, it seems that's not the case, so maybe we should just remove it or call it /runtime

I think keeping /runtime makes sense because it's just the runtimeConfig object (pending a rename there), and perhaps in the future there would be a reason to expose other parts of the object.

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.

florian-lefebvre · 2025-10-16T09:13:30Z

Alright then the virtual module types should live in packages/astro/dev-only.d.ts instead, so they are not shipped to users. You'll also need to update astro's tsconfig:

-"include": ["src"],
+"include": ["src", "dev-only.d.ts"],

EDIT: you won't need to edit the tsconfig when #14538 is merged, soon

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 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

Open

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

matthewp self-assigned this Oct 15, 2025

Uh oh!

Allow adapters to customize headers for fetch requests #14543

Are you sure you want to change the base?

Allow adapters to customize headers for fetch requests #14543

Uh oh!

Conversation

matthewp commented Oct 14, 2025 • edited 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

Footnotes

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!

ematipico Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

matthewp Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ematipico Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

matthewp Oct 15, 2025

Choose a reason for hiding this comment

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!

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

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matthewp commented Oct 14, 2025 •

edited

Loading

changeset-bot bot commented Oct 14, 2025 •

edited

Loading

codspeed-hq bot commented Oct 14, 2025 •

edited

Loading

ematipico Oct 16, 2025 •

edited

Loading

matthewp commented Oct 15, 2025 •

edited

Loading

florian-lefebvre commented Oct 16, 2025 •

edited

Loading