From c62c06d285430148d2db840a1271998438aef70a Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Wed, 2 Jul 2025 12:22:03 +0100 Subject: [PATCH 01/12] feat: document experimental static headers --- .../en/guides/integrations-guide/netlify.mdx | 26 +++++++++++++++++++ .../en/guides/integrations-guide/node.mdx | 26 +++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index 342f77e78bb69..36f6a3437fac3 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -327,6 +327,32 @@ export default defineConfig({ }); ``` +#### `experimentalStaticHeaders` + +

+ **Type:** `boolean`
+

+ +If enabled, the adapter will save [static headers in the framework API file](https://docs.netlify.com/frameworks-api/#headers). + +Here is the list of the headers that are added: +- The CSP header of the static pages is added when CSP support is enabled. + +```js title="astro.config.mjs" {6} +import { defineConfig } from 'astro/config'; +import netlify from '@astrojs/netlify'; + +export default defineConfig({ + experimental: { + cps: true + }, + adapter: netlify({ + experimentalStaticHeaders: true + }) +}); +``` + + ## Examples * The [Astro Netlify Edge Starter](https://github.com/sarahetter/astro-netlify-edge-starter) provides an example and a guide in the README. diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index a4d1d2317ff7d..3d30be2cd9cc2 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -106,6 +106,32 @@ export default defineConfig({ }); ``` + +### `experimentalStaticHeaders` + +

+ **Type:** `boolean`
+

+ +If enabled, the adapter will serve the headers of the static pages using the `Response` object. + +Here is the list of the headers that are added: +- The CSP header of the static pages is added when CSP support is enabled. + +```js title="astro.config.mjs" {6} +import { defineConfig } from 'astro/config'; +import node from '@astrojs/node'; + +export default defineConfig({ + experimental: { + cps: true + }, + adapter: node({ + experimentalStaticHeaders: true + }) +}); +``` + ## Usage First, [performing a build](/en/guides/deploy/#building-your-site-locally). Depending on which `mode` selected (see above) follow the appropriate steps below: From 05cb8d364c09449d6acf116f703a3aca8fb007c7 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 2 Jul 2025 10:56:12 -0300 Subject: [PATCH 02/12] Armand spotted typos Co-authored-by: Armand Philippot --- src/content/docs/en/guides/integrations-guide/netlify.mdx | 2 +- src/content/docs/en/guides/integrations-guide/node.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index 36f6a3437fac3..6e74203fb8b47 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -344,7 +344,7 @@ import netlify from '@astrojs/netlify'; export default defineConfig({ experimental: { - cps: true + csp: true }, adapter: netlify({ experimentalStaticHeaders: true diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index 3d30be2cd9cc2..38a42ba7a1f59 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -124,7 +124,7 @@ import node from '@astrojs/node'; export default defineConfig({ experimental: { - cps: true + csp: true }, adapter: node({ experimentalStaticHeaders: true From cf4d4cea1a9ffabc79643fddd97733fe6f8d47db Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Wed, 2 Jul 2025 14:58:18 +0100 Subject: [PATCH 03/12] Apply suggestions from code review Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- .../docs/en/guides/integrations-guide/netlify.mdx | 9 ++++++--- src/content/docs/en/guides/integrations-guide/node.mdx | 7 ++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index 6e74203fb8b47..63ada9161d6d4 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -331,12 +331,15 @@ export default defineConfig({

**Type:** `boolean`
+ **Default:** `false`
+

-If enabled, the adapter will save [static headers in the framework API file](https://docs.netlify.com/frameworks-api/#headers). +Enables specifying custom headers for prerendered pages in Netlify's configuration. -Here is the list of the headers that are added: -- The CSP header of the static pages is added when CSP support is enabled. +If enabled, the adapter will save [static headers in the Framework API config file](https://docs.netlify.com/frameworks-api/#headers) when provided by Astro features, such as Content Security Policy. + +For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Netlify's configuration, instead of creating a `` element: ```js title="astro.config.mjs" {6} import { defineConfig } from 'astro/config'; diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index 38a42ba7a1f59..4f8f36eaeb361 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -111,12 +111,13 @@ export default defineConfig({

**Type:** `boolean`
+ **Default:** `false`
+

-If enabled, the adapter will serve the headers of the static pages using the `Response` object. +If enabled, the adapter will serve the headers of prerendered pages using the `Response` object when provided by Astro features, such as Content Security Policy. -Here is the list of the headers that are added: -- The CSP header of the static pages is added when CSP support is enabled. +For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP headers to the `Response` object instead of creating a `` element: ```js title="astro.config.mjs" {6} import { defineConfig } from 'astro/config'; From 6257555b2136bde1b268ad3b6c8a550e2a3c7bf1 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 2 Jul 2025 11:33:16 -0300 Subject: [PATCH 04/12] import Since component to node guide --- src/content/docs/en/guides/integrations-guide/node.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index 4f8f36eaeb361..aff8fb7397aec 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -10,6 +10,7 @@ i18nReady: true --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import Since from '~/components/Since.astro'; This adapter allows Astro to deploy your [on-demand rendered routes and features](/en/guides/on-demand-rendering/) to Node targets, including [server islands](/en/guides/server-islands/), [actions](/en/guides/actions/), and [sessions](/en/guides/sessions/). From 68bbbdc8655ca46b130424cf05656f5c7f61c176 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Wed, 2 Jul 2025 15:40:41 +0100 Subject: [PATCH 05/12] Update src/content/docs/en/guides/integrations-guide/netlify.mdx Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/integrations-guide/netlify.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index 63ada9161d6d4..d8aa7d0d45130 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -327,7 +327,11 @@ export default defineConfig({ }); ``` -#### `experimentalStaticHeaders` +## Experimental features + +The following features are also available for use, but may be subject to breaking changes in future updates. Please follow the [`@astrojs/netlify` CHANGELOG](https://github.com/withastro/astro/tree/main/packages/integrations/netlify/CHANGELOG.md) carefully for updates if you are using these features in your project. + +### `experimentalStaticHeaders`

**Type:** `boolean`
From a4fc611c935d84943813de2fbaeda66068513940 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 2 Jul 2025 11:51:56 -0300 Subject: [PATCH 06/12] highlight experimentalStaticHeaders instead of csp line in code samples --- src/content/docs/en/guides/integrations-guide/netlify.mdx | 2 +- src/content/docs/en/guides/integrations-guide/node.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index d8aa7d0d45130..d58283368cac1 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -345,7 +345,7 @@ If enabled, the adapter will save [static headers in the Framework API config fi For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Netlify's configuration, instead of creating a `` element: -```js title="astro.config.mjs" {6} +```js title="astro.config.mjs" {9} import { defineConfig } from 'astro/config'; import netlify from '@astrojs/netlify'; diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index aff8fb7397aec..596985bf2d605 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -120,7 +120,7 @@ If enabled, the adapter will serve the headers of prerendered pages using the `R For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP headers to the `Response` object instead of creating a `` element: -```js title="astro.config.mjs" {6} +```js title="astro.config.mjs" {9} import { defineConfig } from 'astro/config'; import node from '@astrojs/node'; From dded21aba7c11c0b4ac9894f68e76d8ba0e9c0c4 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Wed, 2 Jul 2025 16:25:33 +0100 Subject: [PATCH 07/12] update vercel features --- .../en/guides/integrations-guide/vercel.mdx | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index 8936536e057b4..2158525388575 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -362,6 +362,36 @@ export default defineConfig({ }); ``` +## Experimental features + +The following features are also available for use, but may be subject to breaking changes in future updates. Please follow the [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/tree/main/packages/integrations/vercel/CHANGELOG.md) carefully for updates if you are using these features in your project. + +### `experimentalStaticHeaders` + +**Type:** `boolean`
+**Available for:** Serverless + + +Enables specifying custom headers for prerendered pages in Vercel's configuration. + +If enabled, the adapter will save [static headers in the Vercel `config.json` file](https://vercel.com/docs/project-configuration#headers) when provided by Astro features, such as Content Security Policy. + +For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Netlify's configuration, instead of creating a `` element: + +```js title="astro.config.mjs" {9} +import { defineConfig } from 'astro/config'; +import vercel from '@astrojs/vercel'; + +export default defineConfig({ + experimental: { + csp: true + }, + adapter: vercel({ + experimentalStaticHeaders: true + }) +}); +``` + ### Running Astro middleware on Vercel Edge Functions The `@astrojs/vercel` adapter can create an [edge function](https://vercel.com/docs/functions/edge-functions) from an Astro middleware in your code base. When `edgeMiddleware` is enabled, an edge function will execute your middleware code for all requests including static assets, prerendered pages, and on-demand rendered pages. From 35dc167307be7305717b6412a7989320771ecc79 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 2 Jul 2025 12:50:39 -0300 Subject: [PATCH 08/12] Sarah nits --- src/content/docs/en/guides/integrations-guide/vercel.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index 2158525388575..c73f773053000 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -369,14 +369,15 @@ The following features are also available for use, but may be subject to breakin ### `experimentalStaticHeaders` **Type:** `boolean`
-**Available for:** Serverless + **Default:** `false`
+**Available for:** Serverless
Enables specifying custom headers for prerendered pages in Vercel's configuration. -If enabled, the adapter will save [static headers in the Vercel `config.json` file](https://vercel.com/docs/project-configuration#headers) when provided by Astro features, such as Content Security Policy. +If enabled, the adapter will save [static headers in the Vercel `vercel.json` file](https://vercel.com/docs/project-configuration#headers) when provided by Astro features, such as Content Security Policy. -For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Netlify's configuration, instead of creating a `` element: +For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Vercel configuration, instead of creating a `` element: ```js title="astro.config.mjs" {9} import { defineConfig } from 'astro/config'; From 41204d87168907fde2f1fd5e0d08401705385ea2 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 2 Jul 2025 12:51:32 -0300 Subject: [PATCH 09/12] more Sarah nits --- src/content/docs/en/guides/integrations-guide/netlify.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index d58283368cac1..0511fe60fff51 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -336,14 +336,14 @@ The following features are also available for use, but may be subject to breakin

**Type:** `boolean`
**Default:** `false`
- +

Enables specifying custom headers for prerendered pages in Netlify's configuration. If enabled, the adapter will save [static headers in the Framework API config file](https://docs.netlify.com/frameworks-api/#headers) when provided by Astro features, such as Content Security Policy. -For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Netlify's configuration, instead of creating a `` element: +For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Netlify configuration, instead of creating a `` element: ```js title="astro.config.mjs" {9} import { defineConfig } from 'astro/config'; From 00711fad3d17845e8dc2df9df83e9b4664170db8 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 2 Jul 2025 12:54:22 -0300 Subject: [PATCH 10/12] reorder section headings --- .../en/guides/integrations-guide/vercel.mdx | 74 +++++++++---------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index c73f773053000..a998b5a7c9979 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -362,37 +362,6 @@ export default defineConfig({ }); ``` -## Experimental features - -The following features are also available for use, but may be subject to breaking changes in future updates. Please follow the [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/tree/main/packages/integrations/vercel/CHANGELOG.md) carefully for updates if you are using these features in your project. - -### `experimentalStaticHeaders` - -**Type:** `boolean`
- **Default:** `false`
-**Available for:** Serverless
- - -Enables specifying custom headers for prerendered pages in Vercel's configuration. - -If enabled, the adapter will save [static headers in the Vercel `vercel.json` file](https://vercel.com/docs/project-configuration#headers) when provided by Astro features, such as Content Security Policy. - -For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Vercel configuration, instead of creating a `` element: - -```js title="astro.config.mjs" {9} -import { defineConfig } from 'astro/config'; -import vercel from '@astrojs/vercel'; - -export default defineConfig({ - experimental: { - csp: true - }, - adapter: vercel({ - experimentalStaticHeaders: true - }) -}); -``` - ### Running Astro middleware on Vercel Edge Functions The `@astrojs/vercel` adapter can create an [edge function](https://vercel.com/docs/functions/edge-functions) from an Astro middleware in your code base. When `edgeMiddleware` is enabled, an edge function will execute your middleware code for all requests including static assets, prerendered pages, and on-demand rendered pages. @@ -425,12 +394,6 @@ declare namespace App { } ``` -### Node.js Version Support - -The `@astrojs/vercel` adapter supports specific Node.js versions for deploying your Astro project on Vercel. To view the supported Node.js versions on Vercel, click on the settings tab for a project and scroll down to "Node.js Version" section. - -Check out the [Vercel documentation](https://vercel.com/docs/functions/serverless-functions/runtimes/node-js#default-and-available-versions) to learn more. - ### Sessions The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices. @@ -483,6 +446,43 @@ For example, if you have installed [a Redis integration](https://vercel.com/mark }); ``` +## Node.js Version Support + +The `@astrojs/vercel` adapter supports specific Node.js versions for deploying your Astro project on Vercel. To view the supported Node.js versions on Vercel, click on the settings tab for a project and scroll down to "Node.js Version" section. + +Check out the [Vercel documentation](https://vercel.com/docs/functions/serverless-functions/runtimes/node-js#default-and-available-versions) to learn more. + +## Experimental features + +The following features are also available for use, but may be subject to breaking changes in future updates. Please follow the [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/tree/main/packages/integrations/vercel/CHANGELOG.md) carefully for updates if you are using these features in your project. + +### `experimentalStaticHeaders` + +**Type:** `boolean`
+ **Default:** `false`
+**Available for:** Serverless
+ + +Enables specifying custom headers for prerendered pages in Vercel's configuration. + +If enabled, the adapter will save [static headers in the Vercel `vercel.json` file](https://vercel.com/docs/project-configuration#headers) when provided by Astro features, such as Content Security Policy. + +For example, when [experimental Content Security Policy](/en/reference/experimental-flags/csp/) is enabled, `experimentalStaticHeaders` can be used to add the CSP `headers` to your Vercel configuration, instead of creating a `` element: + +```js title="astro.config.mjs" {9} +import { defineConfig } from 'astro/config'; +import vercel from '@astrojs/vercel'; + +export default defineConfig({ + experimental: { + csp: true + }, + adapter: vercel({ + experimentalStaticHeaders: true + }) +}); +``` + [astro-integration]: /en/guides/integrations-guide/ From 93280aa0bfaee42eb1736998241cc5c75f7d38a6 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 2 Jul 2025 13:07:48 -0300 Subject: [PATCH 11/12] oops, Steps component --- src/content/docs/en/guides/integrations-guide/vercel.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index a998b5a7c9979..cefeee5be80e6 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -446,6 +446,8 @@ For example, if you have installed [a Redis integration](https://vercel.com/mark }); ``` + + ## Node.js Version Support The `@astrojs/vercel` adapter supports specific Node.js versions for deploying your Astro project on Vercel. To view the supported Node.js versions on Vercel, click on the settings tab for a project and scroll down to "Node.js Version" section. @@ -483,6 +485,4 @@ export default defineConfig({ }); ``` - - [astro-integration]: /en/guides/integrations-guide/ From b1fee31bb399d47cffc06ee7307a72e9aa1c2a2c Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Thu, 3 Jul 2025 10:03:35 +0100 Subject: [PATCH 12/12] Update src/content/docs/en/guides/integrations-guide/vercel.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/integrations-guide/vercel.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index cefeee5be80e6..742d16d94ba76 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -460,10 +460,12 @@ The following features are also available for use, but may be subject to breakin ### `experimentalStaticHeaders` +

**Type:** `boolean`
- **Default:** `false`
+**Default:** `false`
**Available for:** Serverless
+

Enables specifying custom headers for prerendered pages in Vercel's configuration.