feat(netlify): add experimental support for static headers (#13952)

ematipico · ascorbic · sarah11918 · web-flow · commit de82ef245407 · 2025-06-16T17:15:45.000+01:00
Co-authored-by: Sarah Rainsberger &lt;5098874+sarah11918@users.noreply.github.com&gt;


Co-authored-by: ascorbic &lt;213306+ascorbic@users.noreply.github.com&gt;
Co-authored-by: sarah11918 &lt;5098874+sarah11918@users.noreply.github.com&gt;
diff --git a/.changeset/huge-crabs-remain.md b/.changeset/huge-crabs-remain.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/underscore-redirects': minor
+---
+
+Adds a new method called `createHostedRouteDefinition`, which returns a `HostRoute` type from a `IntegrationResolvedRoute`.
diff --git a/.changeset/silver-windows-accept.md b/.changeset/silver-windows-accept.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/underscore-redirects': minor
+---
+
+Adds a new method called `printAsRedirects` to print `HostRoutes` as redirects for the `_redirects` file.
diff --git a/.changeset/sixty-icons-camp.md b/.changeset/sixty-icons-camp.md
@@ -0,0 +1,14 @@
+---
+'@astrojs/underscore-redirects': major
+---
+
+- The type `Redirects` has been renamed to `HostRoutes`.
+- `RouteDefinition.target` is now optional
+- `RouteDefinition.weight` is now optional
+- `Redirects.print` has been removed. Now you need to pass `Redirects` type to the `print` function
+
+```diff
+- redirects.print()
++ import { printAsRedirects } from "@astrojs/underscore-redirects"
++ printAsRedirects(redirects)
+```
diff --git a/.changeset/sweet-hotels-cross.md b/.changeset/sweet-hotels-cross.md
@@ -0,0 +1,21 @@
+---
+'@astrojs/netlify': minor
+---
+
+Adds support for the [experimental static headers Astro feature](https://docs.astro.build/en/reference/adapter-reference/#experimentalstaticheaders).
+
+When the feature is enabled via option `experimentalStaticHeaders`, and [experimental Content Security Policy](https://docs.astro.build/en/reference/experimental-flags/csp/) is enabled, the adapter will generate `Response` headers for static pages, which allows support for CSP directives that are not supported inside a `<meta>` tag (e.g. `frame-ancestors`).
+
+```js
+import { defineConfig } from "astro/config";
+import netlify from "@astrojs/netlify";
+
+export default defineConfig({
+  adapter: netlify({
+    experimentalStaticHeaders: true
+  }),
+  experimental: {
+    cps: true
+  }
+})
+```
diff --git a/packages/astro/test/csp.test.js b/packages/astro/test/csp.test.js
@@ -228,7 +228,7 @@ describe('CSP', () => {
 		const $ = cheerio.load(html);
 
 		const meta = $('meta[http-equiv="Content-Security-Policy"]');
-		assert.ok(meta.attr('content').toString().includes('strict-dynamic;'));
+		assert.ok(meta.attr('content').toString().includes("'strict-dynamic';"));
 	});
 
 	it('should serve hashes via headers for dynamic pages, when the strategy is "auto"', async () => {
diff --git a/packages/integrations/cloudflare/src/index.ts b/packages/integrations/cloudflare/src/index.ts
@@ -15,7 +15,7 @@ import {
 	prependForwardSlash,
 	removeLeadingForwardSlash,
 } from '@astrojs/internal-helpers/path';
-import { createRedirectsFromAstroRoutes } from '@astrojs/underscore-redirects';
+import { createRedirectsFromAstroRoutes, printAsRedirects } from '@astrojs/underscore-redirects';
 import { AstroError } from 'astro/errors';
 import { defaultClientConditions } from 'vite';
 import { type GetPlatformProxyOptions, getPlatformProxy } from 'wrangler';
@@ -408,7 +408,10 @@ export default function createIntegration(args?: Options): AstroIntegration {
 
 				if (!trueRedirects.empty()) {
 					try {
-						await appendFile(new URL('./_redirects', _config.outDir), trueRedirects.print());
+						await appendFile(
+							new URL('./_redirects', _config.outDir),
+							printAsRedirects(trueRedirects),
+						);
 					} catch (_error) {
 						logger.error('Failed to write _redirects file');
 					}
diff --git a/packages/integrations/netlify/package.json b/packages/integrations/netlify/package.json
@@ -29,6 +29,7 @@
     "dist"
   ],
   "scripts": {
+    "dev": "astro-scripts dev \"src/**/*.ts\"",
     "build": "astro-scripts build \"src/**/*.ts\" && tsc",
     "build:ci": "astro-scripts build \"src/**/*.ts\"",
     "test": "pnpm run test-fn && pnpm run test-static",
diff --git a/packages/integrations/netlify/src/index.ts b/packages/integrations/netlify/src/index.ts
@@ -3,7 +3,11 @@ import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import type { IncomingMessage } from 'node:http';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { emptyDir } from '@astrojs/internal-helpers/fs';
-import { createRedirectsFromAstroRoutes } from '@astrojs/underscore-redirects';
+import {
+	createHostedRouteDefinition,
+	createRedirectsFromAstroRoutes,
+	printAsRedirects,
+} from '@astrojs/underscore-redirects';
 import type { Context } from '@netlify/functions';
 import type {
 	AstroConfig,
@@ -103,7 +107,11 @@ export function remotePatternToRegex(
 	return regexStr;
 }
 
-async function writeNetlifyFrameworkConfig(config: AstroConfig, logger: AstroIntegrationLogger) {
+async function writeNetlifyFrameworkConfig(
+	config: AstroConfig,
+	staticHeaders: Map<IntegrationResolvedRoute, Headers> | undefined,
+	logger: AstroIntegrationLogger,
+) {
 	const remoteImages: Array<string> = [];
 	// Domains get a simple regex match
 	remoteImages.push(
@@ -116,16 +124,41 @@ async function writeNetlifyFrameworkConfig(config: AstroConfig, logger: AstroInt
 			.filter(Boolean as unknown as (pattern?: string) => pattern is string),
 	);
 
-	const headers = config.build.assetsPrefix
-		? undefined
-		: [
-				{
-					for: `${config.base}${config.base.endsWith('/') ? '' : '/'}${config.build.assets}/*`,
-					values: {
-						'Cache-Control': 'public, max-age=31536000, immutable',
-					},
-				},
-			];
+	const headers = [];
+	if (!config.build.assetsPrefix) {
+		headers.push({
+			for: `${config.base}${config.base.endsWith('/') ? '' : '/'}${config.build.assets}/*`,
+			values: {
+				'Cache-Control': 'public, max-age=31536000, immutable',
+			},
+		});
+	}
+
+	if (staticHeaders && staticHeaders.size > 0) {
+		for (const [route, routeHeaders] of staticHeaders.entries()) {
+			if (!route.isPrerendered) {
+				continue;
+			}
+			if (route.redirect) {
+				continue;
+			}
+
+			const definition = createHostedRouteDefinition(route, config);
+
+			if (config.experimental.csp) {
+				const csp = routeHeaders.get('Content-Security-Policy');
+
+				if (csp) {
+					headers.push({
+						for: definition.input,
+						values: {
+							'Content-Security-Policy': csp,
+						},
+					});
+				}
+			}
+		}
+	}
 
 	// See https://docs.netlify.com/image-cdn/create-integration/
 	const deployConfigDir = new URL('.netlify/v1/', config.root);
@@ -205,6 +238,14 @@ export interface NetlifyIntegrationConfig {
 	 * @default {true}
 	 */
 	imageCDN?: boolean;
+
+	/**
+	 * If enabled, the adapter will save [static headers in the framework API file](https://docs.netlify.com/frameworks-api/#headers).
+	 *
+	 * Here the list of the headers that are added:
+	 * - The CSP header of the static pages is added when CSP support is enabled.
+	 */
+	experimentalStaticHeaders?: boolean;
 }
 
 export default function netlifyIntegration(
@@ -218,6 +259,7 @@ export default function netlifyIntegration(
 	let outDir: URL;
 	let rootDir: URL;
 	let astroMiddlewareEntryPoint: URL | undefined = undefined;
+	let staticHeadersMap: Map<IntegrationResolvedRoute, Headers> | undefined = undefined;
 	// Extra files to be merged with `includeFiles` during build
 	const extraFilesToInclude: URL[] = [];
 	// Secret used to verify that the caller is the astro-generated edge middleware and not a third-party
@@ -271,7 +313,7 @@ export default function netlifyIntegration(
 		});
 
 		if (!redirects.empty()) {
-			await appendFile(new URL('_redirects', outDir), `\n${redirects.print()}\n`);
+			await appendFile(new URL('_redirects', outDir), `\n${printAsRedirects(redirects)}\n`);
 		}
 	}
 
@@ -570,22 +612,22 @@ export default function netlifyIntegration(
 			'astro:routes:resolved': (params) => {
 				routes = params.routes;
 			},
-			'astro:config:done': async ({ config, setAdapter, logger, buildOutput }) => {
+			'astro:config:done': async ({ config, setAdapter, buildOutput }) => {
 				rootDir = config.root;
 				_config = config;
 
 				finalBuildOutput = buildOutput;
 
-				await writeNetlifyFrameworkConfig(config, logger);
-
-				const edgeMiddleware = integrationConfig?.edgeMiddleware ?? false;
+				const useEdgeMiddleware = integrationConfig?.edgeMiddleware ?? false;
+				const useStaticHeaders = integrationConfig?.experimentalStaticHeaders ?? false;
 
 				setAdapter({
 					name: '@astrojs/netlify',
 					serverEntrypoint: '@astrojs/netlify/ssr-function.js',
 					exports: ['default'],
 					adapterFeatures: {
-						edgeMiddleware,
+						edgeMiddleware: useEdgeMiddleware,
+						experimentalStaticHeaders: useStaticHeaders,
 					},
 					args: { middlewareSecret } satisfies Args,
 					supportedAstroFeatures: {
@@ -597,6 +639,9 @@ export default function netlifyIntegration(
 					},
 				});
 			},
+			'astro:build:generated': ({ experimentalRouteToHeaders }) => {
+				staticHeadersMap = experimentalRouteToHeaders;
+			},
 			'astro:build:ssr': async ({ middlewareEntryPoint }) => {
 				astroMiddlewareEntryPoint = middlewareEntryPoint;
 			},
@@ -616,6 +661,8 @@ export default function netlifyIntegration(
 					await writeMiddleware(astroMiddlewareEntryPoint);
 					logger.info('Generated Middleware Edge Function');
 				}
+
+				await writeNetlifyFrameworkConfig(_config, staticHeadersMap, logger);
 			},
 
 			// local dev
diff --git a/packages/integrations/netlify/test/static/fixtures/static-headers/astro.config.mjs b/packages/integrations/netlify/test/static/fixtures/static-headers/astro.config.mjs
@@ -0,0 +1,13 @@
+import netlify from '@astrojs/netlify';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+	output: 'static',
+	adapter: netlify({
+		experimentalStaticHeaders: true
+	}),
+	site: "http://example.com",
+	experimental: {
+		csp: true
+	}
+});
diff --git a/packages/integrations/netlify/test/static/fixtures/static-headers/package.json b/packages/integrations/netlify/test/static/fixtures/static-headers/package.json
@@ -0,0 +1,8 @@
+{
+  "name": "@test/netlify-static-headers",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/netlify": "workspace:"
+  }
+}
diff --git a/packages/integrations/netlify/test/static/fixtures/static-headers/src/components/Island.astro b/packages/integrations/netlify/test/static/fixtures/static-headers/src/components/Island.astro
@@ -0,0 +1 @@
+<p>I am a Server Island</p>
diff --git a/packages/integrations/netlify/test/static/fixtures/static-headers/src/pages/index.astro b/packages/integrations/netlify/test/static/fixtures/static-headers/src/pages/index.astro
@@ -0,0 +1,10 @@
+---
+import Island  from "../components/Island.astro"
+---
+<html>
+<head><title>Index</title></head>
+<body>
+<h1>Index</h1>
+<Island server:defer />
+</body>
+</html>
diff --git a/packages/integrations/netlify/test/static/static-headers.test.js b/packages/integrations/netlify/test/static/static-headers.test.js
@@ -0,0 +1,29 @@
+import * as assert from 'node:assert/strict';
+import { before, describe, it } from 'node:test';
+import { loadFixture } from '../../../../astro/test/test-utils.js';
+
+describe('Static headers', () => {
+	let fixture;
+
+	before(async () => {
+		fixture = await loadFixture({ root: new URL('./fixtures/static-headers/', import.meta.url) });
+		await fixture.build();
+	});
+
+	it('CSP headers are added when CSP is enabled', async () => {
+		const config = await fixture.readFile('../.netlify/v1/config.json');
+		const headers = JSON.parse(config).headers;
+		const index = headers.find((x) => x.for === '/');
+
+		assert.notEqual(index, undefined, 'the index must have CSP headers');
+		assert.notEqual(
+			index.values['Content-Security-Policy'],
+			undefined,
+			'the index must have CSP headers',
+		);
+		assert.ok(
+			index.values['Content-Security-Policy'].includes('script-src'),
+			'must contain the script-src directive because of the server island',
+		);
+	});
+});
diff --git a/packages/underscore-redirects/src/astro.ts b/packages/underscore-redirects/src/astro.ts
@@ -5,7 +5,7 @@ import type {
 	IntegrationResolvedRoute,
 	ValidRedirectStatus,
 } from 'astro';
-import { Redirects } from './redirects.js';
+import { type HostRouteDefinition, HostRoutes } from './host-route.js';
 
 const pathJoin = posix.join;
 
@@ -36,17 +36,17 @@ export function createRedirectsFromAstroRoutes({
 	dir,
 	buildOutput,
 	assets,
-}: CreateRedirectsFromAstroRoutesParams): Redirects {
+}: CreateRedirectsFromAstroRoutesParams): HostRoutes {
 	const base =
 		config.base && config.base !== '/'
 			? config.base.endsWith('/')
 				? config.base.slice(0, -1)
 				: config.base
 			: '';
-	const redirects = new Redirects();
+	const redirects = new HostRoutes();
 
 	for (const [route, dynamicTarget = ''] of routeToDynamicTargetMap) {
-		const distURL = assets.get(route.pattern);
+		const distURL = assets?.get(route.pattern);
 		// A route with a `pathname` is as static route.
 		if (route.pathname) {
 			if (route.redirect) {
@@ -158,3 +158,45 @@ function generateDynamicPattern(route: IntegrationResolvedRoute) {
 function prependForwardSlash(str: string) {
 	return str.startsWith('/') ? str : '/' + str;
 }
+
+/**
+ * Creates a hosted route definition from an `IntegrationResolveRoute`
+ * @param route
+ * @param config
+ */
+export function createHostedRouteDefinition(
+	route: IntegrationResolvedRoute,
+	config: AstroConfig,
+): HostRouteDefinition {
+	const base =
+		config.base && config.base !== '/'
+			? config.base.endsWith('/')
+				? config.base.slice(0, -1)
+				: config.base
+			: '';
+
+	if (route.pattern === '/404') {
+		return {
+			dynamic: true,
+			input: '/*',
+			status: 404,
+		};
+	}
+
+	if (route.pathname) {
+		return {
+			input: `${base}${route.pathname}`,
+			status: 200,
+			dynamic: false,
+		};
+	} else {
+		// This is the dynamic route code. This generates a pattern from a dynamic
+		// route formatted with *s in place of the Astro dynamic/spread syntax.
+		const pattern = generateDynamicPattern(route);
+		return {
+			dynamic: true,
+			input: `${base}${pattern}`,
+			status: 200,
+		};
+	}
+}
diff --git a/packages/underscore-redirects/src/host-route.ts b/packages/underscore-redirects/src/host-route.ts
diff --git a/packages/underscore-redirects/src/index.ts b/packages/underscore-redirects/src/index.ts
diff --git a/packages/underscore-redirects/src/print.ts b/packages/underscore-redirects/src/print.ts
diff --git a/packages/underscore-redirects/test/print.test.js b/packages/underscore-redirects/test/print.test.js
diff --git a/packages/underscore-redirects/test/weight.test.js b/packages/underscore-redirects/test/weight.test.js
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@astrojs/underscore-redirects': minor
 +---
++
 +Adds a new method called `createHostedRouteDefinition`, which returns a `HostRoute` type from a `IntegrationResolvedRoute`.