withastro · ematipico · Jun 13, 2025 · Jun 10, 2025 · Jun 10, 2025 · Jun 10, 2025
diff --git a/.changeset/rare-ducks-sip.md b/.changeset/rare-ducks-sip.md
@@ -0,0 +1,35 @@
+---
+'astro': patch
+---
+
+Adds a new Astro Adapter Feature called `experimentalStaticHeaders` to allow your adapter to receive the `Headers` for rendered static pages.
+
+Adapters that enable support for this feature can access header values directly, affecting their handling of some Astro features such as Content Security Policy (CSP). For example, Astro will no longer serve the CSP `<meta http-equiv="content-security-policy">` element in static pages to adapters with this support.
+
+Astro will serve the value of the header inside a map that can be retrieved from the hook `astro:build:generated`. Adapters can read this mapping and use their hosting headers capabilities to create a configuration file.
+
+A new field called `experimentalRouteToHeaders` will contain a map of `Map<IntegrationResolvedRoute, Headers>` where the `Headers` type contains the headers emitted by the rendered static route. 
+
+To enable support for this experimental Astro Adapter Feature, add it to your `adapterFeatures` in your adapter config:
+
+```js
+// my-adapter.mjs
+export default function createIntegration() {
+  return {
+    name: '@example/my-adapter',
+    hooks: {
+      'astro:config:done': ({ setAdapter }) => {
+        setAdapter({
+          name: '@example/my-adapter',
+          serverEntrypoint: '@example/my-adapter/server.js',
+          adapterFeatures: {
+            experimentalStaticHeaders: true
+          }
+        });
+      },
+    },
+  };
+}
+```
+
+See the [Adapter API docs](https://docs.astro.build/en/reference/adapter-reference/#adapter-features) for more information about providing adapter features.
diff --git a/.changeset/tough-parks-fly.md b/.changeset/tough-parks-fly.md
@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Fixes an issue where the experimental CSP `meta` element wasn't placed in the `<head>` element as early as possible, causing these policies to not apply to styles and scripts that came before the `meta` element.
diff --git a/packages/astro/src/core/app/types.ts b/packages/astro/src/core/app/types.ts
@@ -109,6 +109,7 @@ export type SSRManifestI18n = {
 };
 
 export type SSRManifestCSP = {
+	cspDestination: 'adapter' | 'meta' | 'header' | undefined;
 	algorithm: CspAlgorithm;
 	scriptHashes: string[];
 	scriptResources: string[];

diff --git a/packages/astro/src/core/base-pipeline.ts b/packages/astro/src/core/base-pipeline.ts
@@ -10,9 +10,9 @@ import type {
 	SSRLoadedRenderer,
 	SSRManifest,
 	SSRResult,
+	SSRActions,
 } from '../types/public/internal.js';
 import { createOriginCheckMiddleware } from './app/middlewares.js';
-import type { SSRActions } from './app/types.js';
 import { ActionNotFoundError } from './errors/errors-data.js';
 import { AstroError } from './errors/index.js';
 import type { Logger } from './logger/core.js';

diff --git a/packages/astro/src/core/build/generate.ts b/packages/astro/src/core/build/generate.ts
@@ -16,7 +16,7 @@ import {
 	removeTrailingForwardSlash,
 } from '../../core/path.js';
 import { toFallbackType, toRoutingStrategy } from '../../i18n/utils.js';
-import { runHookBuildGenerated } from '../../integrations/hooks.js';
+import { runHookBuildGenerated, toIntegrationResolvedRoute } from '../../integrations/hooks.js';
 import { getServerOutputDirectory } from '../../prerender/utils.js';
 import type { AstroSettings, ComponentInstance } from '../../types/astro.js';
 import type { GetStaticPathsItem, MiddlewareHandler } from '../../types/public/common.js';
@@ -62,6 +62,7 @@ import type {
 	StylesheetAsset,
 } from './types.js';
 import { getTimeStat, shouldAppendForwardSlash } from './util.js';
+import type { IntegrationResolvedRoute } from '../../types/public/index.js';
 
 export async function generatePages(options: StaticBuildOptions, internals: BuildInternals) {
 	const generatePagesTimer = performance.now();
@@ -102,6 +103,7 @@ export async function generatePages(options: StaticBuildOptions, internals: Buil
 	logger.info('SKIP_FORMAT', `\n${bgGreen(black(` ${verb} static routes `))}`);
 	const builtPaths = new Set<string>();
 	const pagesToGenerate = pipeline.retrieveRoutesToGenerate();
+	const routeToHeaders = new Map<IntegrationResolvedRoute, Headers>();
 	if (ssr) {
 		for (const [pageData, filePath] of pagesToGenerate) {
 			if (pageData.route.prerender) {
@@ -116,13 +118,13 @@ export async function generatePages(options: StaticBuildOptions, internals: Buil
 				const ssrEntryPage = await pipeline.retrieveSsrEntry(pageData.route, filePath);
 
 				const ssrEntry = ssrEntryPage as SinglePageBuiltModule;
-				await generatePage(pageData, ssrEntry, builtPaths, pipeline);
+				await generatePage(pageData, ssrEntry, builtPaths, pipeline, routeToHeaders);
 			}
 		}
 	} else {
 		for (const [pageData, filePath] of pagesToGenerate) {
 			const entry = await pipeline.retrieveSsrEntry(pageData.route, filePath);
-			await generatePage(pageData, entry, builtPaths, pipeline);
+			await generatePage(pageData, entry, builtPaths, pipeline, routeToHeaders);
 		}
 	}
 	logger.info(
@@ -219,7 +221,11 @@ export async function generatePages(options: StaticBuildOptions, internals: Buil
 		delete globalThis?.astroAsset?.addStaticImage;
 	}
 
-	await runHookBuildGenerated({ settings: options.settings, logger });
+	await runHookBuildGenerated({
+		settings: options.settings,
+		logger,
+		experimentalRouteToHeaders: routeToHeaders,
+	});
 }
 
 const THRESHOLD_SLOW_RENDER_TIME_MS = 500;
@@ -229,6 +235,7 @@ async function generatePage(
 	ssrEntry: SinglePageBuiltModule,
 	builtPaths: Set<string>,
 	pipeline: BuildPipeline,
+	routeToHeaders: Map<IntegrationResolvedRoute, Headers>,
 ) {
 	// prepare information we need
 	const { config, logger } = pipeline;
@@ -275,7 +282,7 @@ async function generatePage(
 			logger.info(null, `  ${blue(lineIcon)} ${dim(filePath)}`, false);
 		}
 
-		const created = await generatePath(path, pipeline, generationOptions, route);
+		const created = await generatePath(path, pipeline, generationOptions, route, routeToHeaders);
 
 		const timeEnd = performance.now();
 		const isSlow = timeEnd - timeStart > THRESHOLD_SLOW_RENDER_TIME_MS;
@@ -493,6 +500,7 @@ async function generatePath(
 	pipeline: BuildPipeline,
 	gopts: GeneratePathOptions,
 	route: RouteData,
+	routeToHeaders: Map<IntegrationResolvedRoute, Headers>,
 ): Promise<boolean | undefined> {
 	const { mod } = gopts;
 	const { config, logger, options } = pipeline;
@@ -562,6 +570,13 @@ async function generatePath(
 		throw err;
 	}
 
+	if (
+		pipeline.settings.adapter?.adapterFeatures?.experimentalStaticHeaders &&
+		pipeline.settings.config.experimental?.csp
+	) {
+		routeToHeaders.set(toIntegrationResolvedRoute(route), response.headers);
+	}
+
 	if (response.status >= 300 && response.status < 400) {
 		// Adapters may handle redirects themselves, turning off Astro's redirect handling using `config.build.redirects` in the process.
 		// In that case, we skip rendering static files for the redirect routes.
@@ -659,6 +674,9 @@ async function createBuildManifest(
 		];
 
 		csp = {
+			cspDestination: settings.adapter?.adapterFeatures?.experimentalStaticHeaders
+				? 'adapter'
+				: undefined,
 			styleHashes,
 			styleResources: getStyleResources(settings.config.experimental.csp),
 			scriptHashes,
@@ -681,7 +699,7 @@ async function createBuildManifest(
 		entryModules: Object.fromEntries(internals.entrySpecifierToBundleMap.entries()),
 		inlinedScripts: internals.inlinedScripts,
 		routes: [],
-		adapterName: '',
+		adapterName: settings.adapter?.name ?? '',
 		clientDirectives: settings.clientDirectives,
 		compressHTML: settings.config.compressHTML,
 		renderers,

diff --git a/packages/astro/src/core/build/plugins/plugin-manifest.ts b/packages/astro/src/core/build/plugins/plugin-manifest.ts
@@ -321,6 +321,9 @@ async function buildManifest(
 		];
 
 		csp = {
+			cspDestination: settings.adapter?.adapterFeatures?.experimentalStaticHeaders
+				? 'adapter'
+				: undefined,
 			scriptHashes,
 			scriptResources: getScriptResources(settings.config.experimental.csp),
 			styleHashes,

diff --git a/packages/astro/src/core/render-context.ts b/packages/astro/src/core/render-context.ts
@@ -454,11 +454,6 @@ export class RenderContext {
 			},
 		} satisfies AstroGlobal['response'];
 
-		let cspDestination: 'meta' | 'header' = 'meta';
-		if (!routeData.prerender) {
-			cspDestination = 'header';
-		}
-
 		// Create the result object that will be passed into the renderPage function.
 		// This object starts here as an empty shell (not yet the result) but then
 		// calling the render() function will populate the object with scripts, styles, etc.
@@ -501,7 +496,7 @@ export class RenderContext {
 				extraScriptHashes: [],
 				propagators: new Set(),
 			},
-			cspDestination,
+			cspDestination: manifest.csp?.cspDestination ?? (routeData.prerender ? 'meta' : 'header'),
 			shouldInjectCspMetaTags: !!manifest.csp,
 			cspAlgorithm: manifest.csp?.algorithm ?? 'SHA-256',
 			// The following arrays must be cloned, otherwise they become mutable across routes.

diff --git a/packages/astro/src/integrations/features-validation.ts b/packages/astro/src/integrations/features-validation.ts
@@ -1,4 +1,3 @@
-import { shouldTrackCspHashes } from '../core/csp/common.js';
 import type { Logger } from '../core/logger/core.js';
 import type { AstroSettings } from '../types/astro.js';
 import type {
@@ -39,7 +38,6 @@ export function validateSupportedFeatures(
 		i18nDomains = AdapterFeatureStability.UNSUPPORTED,
 		envGetSecret = AdapterFeatureStability.UNSUPPORTED,
 		sharpImageService = AdapterFeatureStability.UNSUPPORTED,
-		cspHeader = AdapterFeatureStability.UNSUPPORTED,
 	} = featureMap;
 	const validationResult: ValidationResult = {};
 
@@ -95,17 +93,6 @@ export function validateSupportedFeatures(
 		() => settings.config?.image?.service?.entrypoint === 'astro/assets/services/sharp',
 	);
 
-	validationResult.cspHeader = validateSupportKind(
-		cspHeader,
-		adapterName,
-		logger,
-		'cspHeader',
-		() =>
-			settings?.config?.experimental?.csp
-				? shouldTrackCspHashes(settings.config.experimental.csp)
-				: false,
-	);
-
 	return validationResult;
 }
 

diff --git a/packages/astro/src/integrations/hooks.ts b/packages/astro/src/integrations/hooks.ts
@@ -583,9 +583,11 @@ export async function runHookBuildSsr({
 export async function runHookBuildGenerated({
 	settings,
 	logger,
+	experimentalRouteToHeaders,
 }: {
 	settings: AstroSettings;
 	logger: Logger;
+	experimentalRouteToHeaders: Map<IntegrationResolvedRoute, Headers>;
 }) {
 	const dir =
 		settings.buildOutput === 'server' ? settings.config.build.client : settings.config.outDir;
@@ -595,7 +597,7 @@ export async function runHookBuildGenerated({
 			integration,
 			hookName: 'astro:build:generated',
 			logger,
-			params: () => ({ dir }),
+			params: () => ({ dir, experimentalRouteToHeaders }),
 		});
 	}
 }
@@ -679,7 +681,7 @@ export async function runHookRoutesResolved({
 	}
 }
 
-function toIntegrationResolvedRoute(route: RouteData): IntegrationResolvedRoute {
+export function toIntegrationResolvedRoute(route: RouteData): IntegrationResolvedRoute {
 	return {
 		isPrerendered: route.prerender,
 		entrypoint: route.component,

diff --git a/packages/astro/src/runtime/server/render/head.ts b/packages/astro/src/runtime/server/render/head.ts
@@ -16,6 +16,20 @@ const uniqueElements = (item: any, index: number, all: any[]) => {
 
 export function renderAllHeadContent(result: SSRResult) {
 	result._metadata.hasRenderedHead = true;
+	let content = '';
+	if (result.shouldInjectCspMetaTags && result.cspDestination === 'meta') {
+		content += renderElement(
+			'meta',
+			{
+				props: {
+					'http-equiv': 'content-security-policy',
+					content: renderCspContent(result),
+				},
+				children: '',
+			},
+			false,
+		);
+	}
 	const styles = Array.from(result.styles)
 		.filter(uniqueElements)
 		.map((style) =>
@@ -44,28 +58,14 @@ export function renderAllHeadContent(result: SSRResult) {
 	// consist of CSS modules which should naturally take precedence over CSS styles, so the
 	// order will still work. In prod, all CSS are stylesheet links.
 	// In the future, it may be better to have only an array of head elements to avoid these assumptions.
-	let content = styles.join('\n') + links.join('\n') + scripts.join('\n');
+	content += styles.join('\n') + links.join('\n') + scripts.join('\n');
 
 	if (result._metadata.extraHead.length > 0) {
 		for (const part of result._metadata.extraHead) {
 			content += part;
 		}
 	}
 
-	if (result.cspDestination === 'meta') {
-		content += renderElement(
-			'meta',
-			{
-				props: {
-					'http-equiv': 'content-security-policy',
-					content: renderCspContent(result),
-				},
-				children: '',
-			},
-			false,
-		);
-	}
-
 	return markHTMLString(content);
 }
 

diff --git a/packages/astro/src/runtime/server/render/page.ts b/packages/astro/src/runtime/server/render/page.ts
@@ -36,7 +36,7 @@ export async function renderPage(
 			['Content-Type', 'text/html'],
 			['Content-Length', bytes.byteLength.toString()],
 		]);
-		if (result.cspDestination === 'header') {
+		if (result.cspDestination === 'header' || result.cspDestination === 'adapter') {
 			headers.set('content-security-policy', renderCspContent(result));
 		}
 		return new Response(bytes, {
@@ -78,7 +78,7 @@ export async function renderPage(
 	// Create final response from body
 	const init = result.response;
 	const headers = new Headers(init.headers);
-	if (result.shouldInjectCspMetaTags && result.cspDestination === 'header') {
+	if (result.shouldInjectCspMetaTags && result.cspDestination === 'header' || result.cspDestination === 'adapter') {
 		headers.set('content-security-policy', renderCspContent(result));
 	}
 	// For non-streaming, convert string to byte array to calculate Content-Length

diff --git a/packages/astro/src/types/public/integrations.ts b/packages/astro/src/types/public/integrations.ts
@@ -89,6 +89,17 @@ export interface AstroAdapterFeatures {
 	 * Determine the type of build output the adapter is intended for. Defaults to `server`;
 	 */
 	buildOutput?: 'static' | 'server';
+
+	/**
+	 * If supported by the adapter and enabled, Astro won't add any `<meta http-equiv>` tags
+	 * in the static pages, instead it will return a mapping in the
+	 * `astro:build:generated` hook, so adapters can consume them and add them inside
+	 * their hosting headers configuration file.
+	 *
+	 * NOTE: the semantics and list of headers might change until the feature
+	 * is out of experimental
+	 */
+	experimentalStaticHeaders?: boolean;
 }
 
 export interface AstroAdapter {
@@ -136,12 +147,6 @@ export type AstroAdapterFeatureMap = {
 	 * The adapter supports image transformation using the built-in Sharp image service
 	 */
 	sharpImageService?: AdapterSupport;
-
-	/**
-	 * The adapter is able to provide CSP hashes using the Response header `Content-Security-Policy`. Either via hosting configuration
-	 * for static pages or at runtime using `Response` headers for dynamic pages.
-	 */
-	cspHeader?: AdapterSupport;
 };
 
 /**
@@ -233,6 +238,7 @@ export interface BaseIntegrationHooks {
 	'astro:build:generated': (options: {
 		dir: URL;
 		logger: AstroIntegrationLogger;
+		experimentalRouteToHeaders: Map<IntegrationResolvedRoute, Headers>;
 	}) => void | Promise<void>;
 	'astro:build:done': (options: {
 		pages: { pathname: string }[];