Allow adapters to customize headers for fetch requests

.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/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;

packages/astro/src/core/render/ssr-element.ts

@@ -3,21 +3,32 @@ import { fileExtension, joinPaths, prependForwardSlash, slash } from '../../core
 import type { SSRElement } from '../../types/public/internal.js';
 import type { AssetsPrefix, StylesheetAsset } from '../app/types.js';
 
-export function createAssetLink(href: string, base?: string, assetsPrefix?: AssetsPrefix): string {
+export function createAssetLink(
+	href: string,
+	base?: string,
+	assetsPrefix?: AssetsPrefix,
+	queryParams?: URLSearchParams,
+): string {
+	let url = '';
 	if (assetsPrefix) {
 		const pf = getAssetsPrefix(fileExtension(href), assetsPrefix);
-		return joinPaths(pf, slash(href));
+		url = joinPaths(pf, slash(href));
 	} else if (base) {
-		return prependForwardSlash(joinPaths(base, slash(href)));
+		url = prependForwardSlash(joinPaths(base, slash(href)));
 	} else {
-		return href;
+		url = href;
+	}
+	if (queryParams) {
+		url += '?' + queryParams.toString();
 	}
+	return url;
 }
 
 function createStylesheetElement(
 	stylesheet: StylesheetAsset,
 	base?: string,
 	assetsPrefix?: AssetsPrefix,
+	queryParams?: URLSearchParams,
 ): SSRElement {
 	if (stylesheet.type === 'inline') {
 		return {
@@ -28,7 +39,7 @@ function createStylesheetElement(
 		return {
 			props: {
 				rel: 'stylesheet',
-				href: createAssetLink(stylesheet.src, base, assetsPrefix),
+				href: createAssetLink(stylesheet.src, base, assetsPrefix, queryParams),
 			},
 			children: '',
 		};
@@ -39,17 +50,19 @@ export function createStylesheetElementSet(
 	stylesheets: StylesheetAsset[],
 	base?: string,
 	assetsPrefix?: AssetsPrefix,
+	queryParams?: URLSearchParams,
 ): Set<SSRElement> {
-	return new Set(stylesheets.map((s) => createStylesheetElement(s, base, assetsPrefix)));
+	return new Set(stylesheets.map((s) => createStylesheetElement(s, base, assetsPrefix, queryParams)));
 }
 
 export function createModuleScriptElement(
 	script: { type: 'inline' | 'external'; value: string },
 	base?: string,
 	assetsPrefix?: AssetsPrefix,
+	queryParams?: URLSearchParams,
 ): SSRElement {
 	if (script.type === 'external') {
-		return createModuleScriptElementWithSrc(script.value, base, assetsPrefix);
+		return createModuleScriptElementWithSrc(script.value, base, assetsPrefix, queryParams);
 	} else {
 		return {
 			props: {
@@ -64,11 +77,12 @@ function createModuleScriptElementWithSrc(
 	src: string,
 	base?: string,
 	assetsPrefix?: AssetsPrefix,
+	queryParams?: URLSearchParams,
 ): SSRElement {
 	return {
 		props: {
 			type: 'module',
-			src: createAssetLink(src, base, assetsPrefix),
+			src: createAssetLink(src, base, assetsPrefix, queryParams),
 		},
 		children: '',
 	};

packages/astro/src/prefetch/index.ts

@@ -1,7 +1,9 @@
 /*
-  NOTE: Do not add any dependencies or imports in this file so that it can load quickly in dev.
+  NOTE: Be careful about adding dependencies or imports in this file so that it can load quickly in dev.
 */
 
+import { internalFetchHeaders } from 'virtual:astro:adapter-config/client';
+
 const debug = import.meta.env.DEV ? console.debug : undefined;
 const inBrowser = import.meta.env.SSR === false;
 // Track prefetched URLs so we don't prefetch twice
@@ -249,7 +251,12 @@ export function prefetch(url: string, opts?: PrefetchOptions) {
 	// Otherwise, fallback prefetch with fetch
 	else {
 		debug?.(`[astro] Prefetching ${url} with fetch`);
-		fetch(url, { priority: 'low' });
+		// Apply adapter-specific headers for internal fetches
+		const headers = new Headers();
+		for (const [key, value] of Object.entries(internalFetchHeaders) as [string, string][]) {
+			headers.set(key, value);
+		}
+		fetch(url, { priority: 'low', headers });
 	}
 }
 

packages/astro/src/runtime/server/render/server-islands.ts

@@ -186,18 +186,25 @@ export class ServerIslandComponent {
 			);
 		}
 
+		// Get adapter headers for inline script
+		const adapterHeaders = this.result.internalFetchHeaders || {};
+		const headersJson = safeJsonStringify(adapterHeaders);
+
 		const method = useGETRequest
 			? // GET request
-				`let response = await fetch('${serverIslandUrl}');`
+				`const headers = new Headers(${headersJson});
+let response = await fetch('${serverIslandUrl}', { headers });`
 			: // POST request
 				`let data = {
 	componentExport: ${safeJsonStringify(componentExport)},
 	encryptedProps: ${safeJsonStringify(propsEncrypted)},
 	slots: ${safeJsonStringify(renderedSlots)},
 };
+const headers = new Headers({ 'Content-Type': 'application/json', ...${headersJson} });
 let response = await fetch('${serverIslandUrl}', {
 	method: 'POST',
 	body: JSON.stringify(data),
+	headers,
 });`;
 
 		this.islandContent = `${method}replaceServerIsland('${hostId}', response);`;

packages/astro/src/transitions/router.ts

@@ -1,3 +1,4 @@
+import { internalFetchHeaders } from 'virtual:astro:adapter-config/client';
 import type { TransitionBeforePreparationEvent } from './events.js';
 import { doPreparation, doSwap, TRANSITION_AFTER_SWAP } from './events.js';
 import { detectScriptExecuted } from './swap-functions.js';
@@ -99,7 +100,12 @@ async function fetchHTML(
 	init?: RequestInit,
 ): Promise<null | { html: string; redirected?: string; mediaType: DOMParserSupportedType }> {
 	try {
-		const res = await fetch(href, init);
+		// Apply adapter-specific headers for internal fetches
+		const headers = new Headers(init?.headers);
+		for (const [key, value] of Object.entries(internalFetchHeaders) as [string, string][]) {
+			headers.set(key, value);
+		}
+		const res = await fetch(href, { ...init, headers });
 		const contentType = res.headers.get('content-type') ?? '';
 		// drop potential charset (+ other name/value pairs) as parser needs the mediaType
 		const mediaType = contentType.split(';', 1)[0].trim();

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

@@ -115,6 +115,21 @@ export interface AstroAdapter {
 	 * If the adapter is not able to handle certain configurations, Astro will throw an error.
 	 */
 	supportedAstroFeatures: AstroAdapterFeatureMap;
+	/**
+	 * Configuration for Astro's client-side code.
+	 */
+	client?: {
+		/**
+		 * Headers to inject into Astro's internal fetch calls (Actions, View Transitions, Server Islands, Prefetch).
+		 * Can be an object of headers or a function that returns headers.
+		 */
+		internalFetchHeaders?: Record<string, string> | (() => Record<string, string>);
+		/**
+		 * Query parameters to append to all asset URLs (images, stylesheets, scripts, etc.).
+		 * Useful for adapters that need to track deployment versions or other metadata.
+		 */
+		assetQueryParams?: URLSearchParams;
+	};
 }
 
 export type AstroAdapterFeatureMap = {

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

@@ -270,6 +270,7 @@ export interface SSRResult {
 	styleResources: SSRManifestCSP['styleResources'];
 	directives: SSRManifestCSP['directives'];
 	isStrictDynamic: SSRManifestCSP['isStrictDynamic'];
+	internalFetchHeaders?: Record<string, string>;
 }
 
 /**

packages/astro/src/virtual-modules/actions.ts

@@ -1,4 +1,5 @@
 import { shouldAppendTrailingSlash } from 'virtual:astro:actions/options';
+import { internalFetchHeaders } from 'virtual:astro:adapter-config/client';
 import type { ActionClient, SafeResult } from '../actions/runtime/server.js';
 import {
 	ACTION_QUERY_PARAMS,
@@ -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/vite-plugin-adapter-config/index.ts

@@ -0,0 +1,41 @@
+import type { Plugin as VitePlugin } from 'vite';
+import type { AstroSettings } from '../types/astro.js';
+
+const VIRTUAL_CLIENT_ID = 'virtual:astro:adapter-config/client';
+const RESOLVED_VIRTUAL_CLIENT_ID = '\0' + VIRTUAL_CLIENT_ID;
+
+export function vitePluginAdapterConfig(settings: AstroSettings): VitePlugin {
+	return {
+		name: 'astro:adapter-config',
+		resolveId(id) {
+			if (id === VIRTUAL_CLIENT_ID) {
+				return RESOLVED_VIRTUAL_CLIENT_ID;
+			}
+		},
+		load(id, options) {
+			if (id === RESOLVED_VIRTUAL_CLIENT_ID) {
+				// During SSR, return empty headers to avoid any runtime issues
+				if (options?.ssr) {
+					return {
+						code: `export const internalFetchHeaders = {};`,
+					};
+				}
+
+				const adapter = settings.adapter;
+				const clientConfig = adapter?.client || {};
+
+				let internalFetchHeaders = {};
+				if (clientConfig.internalFetchHeaders) {
+					internalFetchHeaders =
+						typeof clientConfig.internalFetchHeaders === 'function'
+							? clientConfig.internalFetchHeaders()
+							: clientConfig.internalFetchHeaders;
+				}
+
+				return {
+					code: `export const internalFetchHeaders = ${JSON.stringify(internalFetchHeaders)};`,
+				};
+			}
+		},
+	};
+}