Allow adapters to customize headers for fetch requests (#14543)

* feat: add adapter support for internal fetch headers (Netlify skew protection)

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

* fix: resolve TypeScript errors in adapter config implementation

- 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

* refactor: extract internalFetchHeaders from manifest into SSRResult

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.

* Address PR feedback: clean up tests and update comment

- 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

* Fix skew protection test to check correct manifest file

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

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

* review changes

* Update .changeset/netlify-skew-protection.md

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

* fix lint

* Update packages/astro/dev-only.d.ts

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

* Add assetQueryParams support for skew protection

This adds a new `assetQueryParams` configuration option to the adapter client config that allows adapters to append query parameters to all static asset URLs. This is used for Vercel's skew protection to track deployment versions.

Changes:
- Extended AstroAdapter.client interface with assetQueryParams property
- Modified getAssetsPrefix() to accept and append query parameters
- Updated manifest builder to include query params in all asset URLs
- Updated SSR element creation functions to support query params
- Updated Vercel adapter to provide deployment ID as query param when skew protection is enabled

This ensures that all asset requests include the deployment identifier, allowing Vercel to route them to the correct deployment version if there's a version mismatch between client and server.

* update imports

* update based on review comments

* switch to use URLSearchParams

* remove unneeded file

* align vercel impl with how the other works

* focus changesets a bit more

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

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

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

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

* explain how to do it yourself too

* oops

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

Co-authored-by: Steven <steven@ceriously.com>

---------

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>
Co-authored-by: Steven <steven@ceriously.com>

Author: 4 people

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

@@ -0,0 +1,11 @@
+---
+'astro': minor
+---
+
+Adds two new adapter configuration options `assetQueryParams` and `internalFetchHeaders` to the Adapter API.
+
+Official and community-built adapters can now use `client.assetQueryParams` to specify query parameters that should be appended to asset URLs (CSS, JavaScript, images, fonts, etc.). The query parameters are automatically appended to all generated asset URLs during the build process.
+
+Adapters can also use `client.internalFetchHeaders` to specify headers that should be included in Astro's internal fetch calls (Actions, View Transitions, Server Islands, Prefetch).
+
+This enables features like Netlify's skew protection, which requires the deploy ID to be sent with both internal requests and asset URLs to ensure client and server versions match during deployments.

.changeset/netlify-assetqueryparams.md

@@ -0,0 +1,15 @@
+---
+'@astrojs/netlify': minor
+---
+
+Enables Netlify's skew protection feature for Astro sites deployed on Netlify. Skew protection ensures that your site's client and server versions stay synchronized during deployments, preventing issues where users might load assets from a newer deployment while the server is still running the older version.
+
+When you deploy to Netlify, the deployment ID is now automatically included in both asset requests and API calls, allowing Netlify to serve the correct version to every user. These are set for built-in features (Actions, View Transitions, Server Islands, Prefetch). If you are making your own fetch requests to your site, you can include the header manually using the `DEPLOY_ID` environment variable:
+
+```js
+const response = await fetch('/api/endpoint', {
+  headers: {
+    'X-Netlify-Deploy-ID': import.meta.env.DEPLOY_ID,
+  },
+});
+```

.changeset/vercel-fixes.md

@@ -0,0 +1,7 @@
+---
+'@astrojs/vercel': minor
+---
+
+Enables skew protection for Astro sites deployed on Vercel. Skew protection ensures that your site's client and server versions stay synchronized during deployments, preventing issues where users might load assets from a newer deployment while the server is still running the older version.
+
+Skew protection is automatically enabled on Vercel deployments when the `VERCEL_SKEW_PROTECTION_ENABLED` environment variable is set to `1`. The deployment ID is automatically included in both asset requests and API calls, allowing Vercel to serve the correct version to every user.

packages/astro/dev-only.d.ts

@@ -11,6 +11,10 @@ declare module 'virtual:astro:assets/fonts/internal' {
 	export const consumableMap: import('./src/assets/fonts/types.js').ConsumableMap;
 }
 
+declare module 'virtual:astro:adapter-config/client' {
+	export const internalFetchHeaders: Record<string, string>;
+}
+
 declare module 'virtual:astro:actions/options' {
 	export const shouldAppendTrailingSlash: boolean;
 }

packages/astro/src/actions/runtime/virtual.ts

@@ -1,4 +1,5 @@
 import { shouldAppendTrailingSlash } from 'virtual:astro:actions/options';
+import { internalFetchHeaders } from 'virtual:astro:adapter-config/client';
 import type { APIContext } from '../../types/public/context.js';
 import type { ActionClient, SafeResult } from './server.js';
 import {
@@ -94,6 +95,10 @@ async function handleAction(
 	// When running client-side, make a fetch request to the action path.
 	const headers = new Headers();
 	headers.set('Accept', 'application/json');
+	// Apply adapter-specific headers for internal fetches
+	for (const [key, value] of Object.entries(internalFetchHeaders)) {
+		headers.set(key, value);
+	}
 	let body = param;
 	if (!(body instanceof FormData)) {
 		try {

packages/astro/src/assets/utils/getAssetsPrefix.ts

@@ -1,12 +1,19 @@
 import type { AssetsPrefix } from '../../core/app/types.js';
 
-export function getAssetsPrefix(fileExtension: string, assetsPrefix?: AssetsPrefix): string {
-	if (!assetsPrefix) return '';
-	if (typeof assetsPrefix === 'string') return assetsPrefix;
-	// we assume the file extension has a leading '.' and we remove it
-	const dotLessFileExtension = fileExtension.slice(1);
-	if (assetsPrefix[dotLessFileExtension]) {
-		return assetsPrefix[dotLessFileExtension];
+export function getAssetsPrefix(
+	fileExtension: string,
+	assetsPrefix?: AssetsPrefix,
+): string {
+	let prefix = '';
+	if (!assetsPrefix) {
+		prefix = '';
+	} else if (typeof assetsPrefix === 'string') {
+		prefix = assetsPrefix;
+	} else {
+		// we assume the file extension has a leading '.' and we remove it
+		const dotLessFileExtension = fileExtension.slice(1);
+		prefix = assetsPrefix[dotLessFileExtension] || assetsPrefix.fallback;
 	}
-	return assetsPrefix.fallback;
+
+	return prefix;
 }

packages/astro/src/core/app/types.ts

@@ -95,6 +95,7 @@ export type SSRManifest = {
 	buildClientDir: string | URL;
 	buildServerDir: string | URL;
 	csp: SSRManifestCSP | undefined;
+	internalFetchHeaders?: Record<string, string>;
 };
 
 export type SSRActions = {

packages/astro/src/core/build/plugins/plugin-manifest.ts

@@ -202,13 +202,21 @@ async function buildManifest(
 		staticFiles.push(entryModules[PAGE_SCRIPT_ID]);
 	}
 
+	const assetQueryParams = settings.adapter?.client?.assetQueryParams;
+	const assetQueryString = assetQueryParams ? assetQueryParams.toString() : undefined;
+
 	const prefixAssetPath = (pth: string) => {
+		let result = '';
 		if (settings.config.build.assetsPrefix) {
 			const pf = getAssetsPrefix(fileExtension(pth), settings.config.build.assetsPrefix);
-			return joinPaths(pf, pth);
+			result = joinPaths(pf, pth);
 		} else {
-			return prependForwardSlash(joinPaths(settings.config.base, pth));
+			result = prependForwardSlash(joinPaths(settings.config.base, pth));
+		}
+		if (assetQueryString) {
+			result += '?' + assetQueryString;
 		}
+		return result;
 	};
 
 	// Default components follow a special flow during build. We prevent their processing earlier
@@ -341,6 +349,18 @@ async function buildManifest(
 		};
 	}
 
+	// Get internal fetch headers from adapter config
+	let internalFetchHeaders: Record<string, string> | undefined = undefined;
+	if (settings.adapter?.client?.internalFetchHeaders) {
+		const headers =
+			typeof settings.adapter.client.internalFetchHeaders === 'function'
+				? settings.adapter.client.internalFetchHeaders()
+				: settings.adapter.client.internalFetchHeaders;
+		if (Object.keys(headers).length > 0) {
+			internalFetchHeaders = headers;
+		}
+	}
+
 	return {
 		hrefRoot: opts.settings.config.root.toString(),
 		cacheDir: opts.settings.config.cacheDir.toString(),
@@ -372,5 +392,6 @@ async function buildManifest(
 		key: encodedKey,
 		sessionConfig: settings.config.session,
 		csp,
+		internalFetchHeaders,
 	};
 }

packages/astro/src/core/create-vite.ts

@@ -21,6 +21,7 @@ import astroPrefetch from '../prefetch/vite-plugin-prefetch.js';
 import astroDevToolbar from '../toolbar/vite-plugin-dev-toolbar.js';
 import astroTransitions from '../transitions/vite-plugin-transitions.js';
 import type { AstroSettings, RoutesList } from '../types/astro.js';
+import { vitePluginAdapterConfig } from '../vite-plugin-adapter-config/index.js';
 import astroVitePlugin from '../vite-plugin-astro/index.js';
 import astroPostprocessVitePlugin from '../vite-plugin-astro-postprocess/index.js';
 import { vitePluginAstroServer } from '../vite-plugin-astro-server/index.js';
@@ -156,6 +157,7 @@ export async function createVite(
 			command === 'dev' && vitePluginAstroServer({ settings, logger, fs, routesList, manifest }), // manifest is only required in dev mode, where it gets created before a Vite instance is created, and get passed to this function
 			importMetaEnv({ envLoader }),
 			astroEnv({ settings, sync, envLoader }),
+			vitePluginAdapterConfig(settings),
 			markdownVitePlugin({ settings, logger }),
 			htmlVitePlugin(),
 			astroPostprocessVitePlugin(),

packages/astro/src/core/render-context.ts

@@ -572,6 +572,7 @@ export class RenderContext {
 			styleResources: manifest.csp?.styleResources ? [...manifest.csp.styleResources] : [],
 			directives: manifest.csp?.directives ? [...manifest.csp.directives] : [],
 			isStrictDynamic: manifest.csp?.isStrictDynamic ?? false,
+			internalFetchHeaders: manifest.internalFetchHeaders,
 		};
 
 		return result;