Skip to content

[BETA] ci: update reference docs #12917

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sarah11918 merged 2 commits into from
Dec 16, 2025
Merged

[BETA] ci: update reference docs #12917

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
675a16d
ci: update reference docs
sarah11918 Dec 16, 2025
2a2a0bb
Merge branch 'v6' into ci/docgen-beta
sarah11918 Dec 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 135 additions & 69 deletions src/content/docs/en/reference/configuration-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,23 +376,21 @@ Using `'attribute'` is useful when you are manipulating the `class` attribute of
</p>

Determines the default behavior when two routes generate the same prerendered URL:

- `error`: fail the build and display an error, forcing you to resolve the conflict
- `warn` (default): log a warning when conflicts occur, but build using the highest-priority route
- `ignore`: silently build using the highest-priority route when conflicts occur
- `error`: fail the build and display an error, forcing you to resolve the conflict
- `warn` (default): log a warning when conflicts occur, but build using the highest-priority route
- `ignore`: silently build using the highest-priority route when conflicts occur

```js
{
prerenderConflictBehavior: 'error'
}
```


### vite

<p>

**Type:** `ViteUserConfig`
**Type:** `ViteUserConfig`
</p>

Pass additional configuration options to Vite. Useful when Astro doesn't support some advanced configuration that you may need.
Expand Down Expand Up @@ -421,7 +419,7 @@ View the full `vite` configuration object documentation on [vite.dev](https://vi
}
```

## security
### security

<p>

Expand All @@ -434,16 +432,6 @@ Enables security measures for an Astro website.

These features only exist for pages rendered on demand (SSR) using `server` mode or pages that opt out of prerendering in `static` mode.


### security.checkOrigin

<p>

**Type:** `boolean`<br />
**Default:** `true`<br />
<Since v="4.9.0" />
</p>

By default, Astro will automatically check that the “origin” header
matches the URL sent by each request in on-demand rendered pages. You can
disable this behavior by setting `checkOrigin` to `false`:
Expand All @@ -458,18 +446,27 @@ export default defineConfig({
})
```

#### security.checkOrigin

<p>

**Type:** `boolean`<br />
**Default:** `true`<br />
<Since v="4.9.0" />
</p>

Performs a check that the "origin" header, automatically passed by all modern browsers, matches the URL sent by each `Request`. This is used to provide Cross-Site Request Forgery (CSRF) protection.

The "origin" check is executed only for pages rendered on demand, and only for the requests `POST`, `PATCH`, `DELETE` and `PUT` with
one of the following `content-type` headers: `'application/x-www-form-urlencoded'`, `'multipart/form-data'`, `'text/plain'`.

If the "origin" header doesn't match the `pathname` of the request, Astro will return a 403 status code and will not render the page.

### security.allowedDomains
#### security.allowedDomains

<p>

**Type:** `RemotePattern[]`<br />
**Type:** `Array<RemotePattern>`<br />
**Default:** `[]`<br />
<Since v="5.14.2" />
</p>
Expand Down Expand Up @@ -503,52 +500,51 @@ The patterns support wildcards for flexible hostname matching:

When not configured, `X-Forwarded-Host` headers are not trusted and will be ignored.


### `security.csp`
#### security.csp

<p>

**Type:** `boolean | object`<br />
**Default:** `false`<br />
<Since v="6.0.0" />
</p>

Enables support for [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) to help minimize certain types of security threats by controlling which resources a document is allowed to load. This provides additional protection against [cross-site scripting (XSS)](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting) attacks.

Enabling this feature adds additional security to **Astro's handling of processed and bundled scripts and styles** by default, and allows you to further configure these, and additional, content types.
Enabling this feature adds additional security to Astro's handling of processed and bundled scripts and styles by default, and allows you to further configure these, and additional, content types.

This feature comes with some limitations:
- External scripts and external styles are not supported out of the box, but you can [provide your own hashes](#hashes).
- [Astro's view transitions](/en/guides/view-transitions/) using the `<ClientRouter />` are not supported, but you can [consider migrating to the browser native View Transition API](https://events-3bg.pages.dev/jotter/astro-view-transitions/) instead if you are not using Astro's enhancements to the native View Transitions and Navigation APIs.
This feature comes with some limitations:
- External scripts and external styles are not supported out of the box, but you can [provide your own hashes](https://v6.docs.astro.build/en/reference/configuration-reference/#hashes).
- [Astro's view transitions](https://v6.docs.astro.build/en/guides/view-transitions/) using the `<ClientRouter />` are not supported, but you can [consider migrating to the browser native View Transition API](https://events-3bg.pages.dev/jotter/astro-view-transitions/) instead if you are not using Astro's enhancements to the native View Transitions and Navigation APIs.
- Shiki isn't currently supported. By design, Shiki functions using inline styles.

:::note
Due to the nature of the Vite dev server, this feature isn't supported while working in `dev` mode. Instead, you can test this in your Astro project using `build` and `preview`.
:::

When enabled, Astro will add a `<meta>` element inside the `<head>` element of each page.

This element will have the `http-equiv="content-security-policy"` attribute, and the `content` attribute will provide values for the `script-src` and `style-src` [directives](#securitycspdirectives) based on the script and styles used in the page.
This element will have the `http-equiv="content-security-policy"` attribute, and the `content` attribute will provide values for the `script-src` and `style-src` [directives](https://v6.docs.astro.build/en/reference/configuration-reference/#securitycspdirectives) based on the script and styles used in the page.

```html

<head>
<meta
http-equiv="content-security-policy"
content="
script-src 'self' 'sha256-somehash';
script-src 'self' 'sha256-somehash';
style-src 'self' 'sha256-somehash';
"
>
</head>
```


You can further customize the `<meta>` element by enabling this feature with a configuration object that includes additional options.

##### `security.csp.algorithm`
##### security.csp.algorithm

<p>

**Type:** `'SHA-256' | 'SHA-512' | 'SHA-384'`<br />
**Type:** `"SHA-256" | "SHA-384" | "SHA-512"`<br />
**Default:** `'SHA-256'`<br />
<Since v="6.0.0" />
</p>
Expand All @@ -567,11 +563,11 @@ export default defineConfig({
});
```

##### `security.csp.directives`
##### security.csp.directives

<p>

**Type:** `CspDirective[]`<br />
**Type:** `Array<string>`<br />
**Default:** `[]`<br />
<Since v="6.0.0" />
</p>
Expand All @@ -585,14 +581,13 @@ export default defineConfig({
security: {
csp: {
directives: [
"default-src 'self'",
"default-src 'self'",
"img-src 'self' https://images.cdn.example.com"
]
}
}
});
```

After the build, the `<meta>` element will add your directives into the `content` value alongside Astro's default directives:

```html
Expand All @@ -607,38 +602,69 @@ After the build, the `<meta>` element will add your directives into the `content
>
```

##### `security.csp.styleDirective`
##### security.csp.styleDirective

<p>

**Type:** `object`<br />
**Default:** `{}`<br />
**Type:** `CspStyleDirective`<br />
**Default:** `undefined`<br />
<Since v="6.0.0" />
</p>

A configuration object that allows you to override the default sources for the `style-src` directive with the [`resources`](#resources) property, or to provide additional [hashes](#hashes) to be rendered.
A configuration object that allows you to override the default sources for the `style-src` directive with the [`resources`](https://v6.docs.astro.build/en/reference/configuration-reference/#resources) property, or to provide additional [hashes](https://v6.docs.astro.build/en/reference/configuration-reference#hashes) to be rendered.

##### `security.csp.scriptDirective`
###### security.csp.styleDirective.hashes

<p>

**Type:** `object`<br />
**Default:** `{}`<br />
<Since v="6.0.0" />
**Type:** `Array<CspHash>`<br />
**Default:** `[]`<br />
<Since v="6.0.0" />
</p>

A configuration object that allows you to override the default sources for the `script-src` directive with the [`resources`](#resources) property, or to provide additional [hashes](#hashes) to be rendered.
A list of additional hashes to be rendered.

You must provide hashes that start with `sha384-`, `sha512-` or `sha256-`. Other values will cause a validation error. These hashes are added to all pages.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
security: {
csp: {
styleDirective: {
hashes: [
"sha384-styleHash",
"sha512-styleHash",
"sha256-styleHash"
]
}
}
}
});
```

After the build, the `<meta>` element will include your additional hashes in the `style-src` directives:

```html
<meta
http-equiv="content-security-policy"
content="
style-src 'self' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash' 'sha256-generatedByAstro';
"
>
```

##### `resources`
###### security.csp.styleDirective.resources

<p>

**Type:** `string[]`<br />
**Type:** `Array<string>`<br />
**Default:** `[]`<br />
<Since v="6.0.0" />
</p>

A list of valid sources for the `script-src` and `style-src` directives to override Astro's default sources. This will not include `'self'` by default, and must be included in this list if you wish to keep it. These resources are added to all pages.
A list of valid sources for `style-src` directives to override Astro's default sources. This will not include `'self'` by default, and must be included in this list if you wish to keep it. These resources are added to all pages.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
Expand All @@ -651,38 +677,43 @@ export default defineConfig({
"'self'",
"https://styles.cdn.example.com"
]
},
scriptDirective: {
resources: [
"https://cdn.example.com"
]
}
}
}
});
```
```

After the build, the `<meta>` element will instead apply your sources to the `style-src` and `script-src` directives:
After the build, the `<meta>` element will instead apply your sources to the `style-src` directives:

```html
<head>
<meta
http-equiv="content-security-policy"
content="
script-src https://cdn.example.com 'sha256-somehash';
style-src 'self' https://styles.cdn.example.com 'sha256-somehash';
"
style-src 'self' https://styles.cdn.example.com 'sha256-somehash';
"
>
</head>
```

When resources are inserted multiple times or from multiple sources (e.g. defined in your `csp` config and added using [the CSP runtime API](/en/reference/api-reference/#csp)), Astro will merge and deduplicate all resources to create your `<meta>` element.

#### `hashes`
##### security.csp.scriptDirective

<p>

**Type:** `CspScriptDirective`<br />
**Default:** `undefined`<br />
<Since v="6.0.0" />
</p>

A configuration object that allows you to override the default sources for the `script-src` directive with the [`resources`](https://v6.docs.astro.build/en/reference/configuration-reference/#resources) property, or to provide additional [hashes](https://v6.docs.astro.build/en/reference/configuration-reference#hashes) to be rendered.

###### security.csp.scriptDirective.hashes

<p>

**Type:** `CspHash[]`<br />
**Type:** `Array<CspHash>`<br />
**Default:** `[]`<br />
<Since v="6.0.0" />
</p>
Expand All @@ -697,13 +728,6 @@ import { defineConfig } from 'astro/config';
export default defineConfig({
security: {
csp: {
styleDirective: {
hashes: [
"sha384-styleHash",
"sha512-styleHash",
"sha256-styleHash"
]
},
scriptDirective: {
hashes: [
"sha384-scriptHash",
Expand All @@ -716,19 +740,60 @@ export default defineConfig({
});
```

After the build, the `<meta>` element will include your additional hashes in the `script-src` and `style-src` directives:
After the build, the `<meta>` element will include your additional hashes in the `script-src` directives:

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self' 'sha384-scriptHash' 'sha512-scriptHash' 'sha256-scriptHash' 'sha256-generatedByAstro';
style-src 'self' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash' 'sha256-generatedByAstro';
"
>
```

#### `strictDynamic`
###### security.csp.scriptDirective.resources

<p>

**Type:** `Array<string>`<br />
**Default:** `[]`<br />
<Since v="6.0.0" />
</p>

A list of valid sources for the `script-src` directives to override Astro's default sources. This will not include `'self'` by default, and must be included in this list if you wish to keep it. These resources are added to all pages.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
security: {
csp: {
scriptDirective: {
resources: [
"'self'", "https://cdn.example.com"
]
}
}
}
});
```

After the build, the `<meta>` element will instead apply your sources to the `script-src` directives:

```html
<head>
<meta
http-equiv="content-security-policy"
content="
script-src 'self' https://cdn.example.com 'sha256-somehash';
"
>
</head>
```

When resources are inserted multiple times or from multiple sources (e.g. defined in your `csp` config and added using [the CSP runtime API](/en/reference/api-reference/#csp)), Astro will merge and deduplicate all resources to create your `<meta>` element.

###### security.csp.scriptDirective.strictDynamic

<p>

Expand Down Expand Up @@ -2061,3 +2126,4 @@ export default defineConfig({
}
})
```