Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions astro.sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,7 @@ export const sidebar = [
'reference/experimental-flags/content-intellisense',
'reference/experimental-flags/chrome-devtools-workspace',
'reference/experimental-flags/svg-optimization',
'reference/experimental-flags/collection-storage',
],
}),
'reference/legacy-flags',
Expand Down
110 changes: 105 additions & 5 deletions src/content/docs/en/reference/api-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1086,6 +1086,14 @@ You can customize the `<meta>` element per page from the `Astro` global inside `

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

:::caution[Scoping to more specific directives]
When you scope a source or hash to a more specific directive with the `kind` option (`'element'` or `'attribute'`), browsers use that directive instead of the generic `script-src`/`style-src` for its scope, and do not fall back to the generic directive.

Astro automatically moves the hashes it generates for your inline scripts and styles onto the more specific directive so they keep working. However, it does **not** move your generic (`'default'`) resources. If you combine generic resources with more specific resources or hashes for the same directive family, the generic resources will not apply to the specific scope. Astro logs a warning if it detects such a situation.

To fix the issue, move all the resources and hashes to the specific directives.
:::


#### `csp.insertDirective()`

Expand Down Expand Up @@ -1122,7 +1130,7 @@ content="

<p>

**Type:** `(resource: string) => void`<br />
**Type:** `(resource: string | { resource: string; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1146,11 +1154,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

You can also scope a source to a more specific directive by passing an object with a `kind` property. Use `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare string) for `style-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertStyleResource({ resource: "'unsafe-inline'", kind: "attribute" });
---
```

After the build, the `<meta>` element for this individual page will add your source to the `style-src-attr` directive, which applies only to inline `style` attributes:

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
style-src 'self';
style-src-attr 'unsafe-inline';
"
>
```

#### `csp.insertStyleHash()`

<p>

**Type:** `(hash: CspHash) => void`<br />
**Type:** `(hash: CspHash | { hash: CspHash; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1174,11 +1205,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

You can also scope a hash to a more specific directive by passing an object with a `kind` property. Use `'element'` for `style-src-elem`, `'attribute'` for `style-src-attr`, or `'default'` (the same as a bare hash) for `style-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertStyleHash({ hash: "sha512-styleHash", kind: "element" });
---
```

After the build, the `<meta>` element for this individual page will add your hash to the `style-src-elem` directive. Astro's automatically generated style hashes also move there, since `style-src-elem` takes precedence over `style-src` for `<style>` and `<link>` elements:

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

#### `csp.insertScriptResource()`

<p>

**Type:** `(resource: string) => void`<br />
**Type:** `(resource: string | { resource: string; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1202,11 +1256,34 @@ content="
>
```

<p><Since v="7.1.0" /></p>

You can also scope a source to a more specific directive by passing an object with a `kind` property. Use `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare string) for `script-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertScriptResource({ resource: "https://scripts.cdn.example.com", kind: "element" });
---
```

After the build, the `<meta>` element for this individual page will add your source to the `script-src-elem` directive, which governs `<script>` elements:

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

#### `csp.insertScriptHash()`

<p>

**Type:** `(hash: CspHash) => void`<br />
**Type:** `(hash: CspHash | { hash: CspHash; kind: 'element' | 'attribute' | 'default' }) => void`<br />
<Since v="6.0.0" />
</p>

Expand All @@ -1224,7 +1301,30 @@ After the build, the `<meta>` element for this individual page will add your has
<meta
http-equiv="content-security-policy"
content="
script-src 'self' 'sha256-somehash' 'sha512-styleHash';
script-src 'self' 'sha256-somehash' 'sha512-scriptHash';
style-src 'self' 'sha256-somehash';
"
>
```

<p><Since v="7.1.0" /></p>

You can also scope a hash to a more specific directive by passing an object with a `kind` property. Use `'element'` for `script-src-elem`, `'attribute'` for `script-src-attr`, or `'default'` (the same as a bare hash) for `script-src`.

```astro title="src/pages/index.astro"
---
Astro.csp?.insertScriptHash({ hash: "sha512-scriptHash", kind: "element" });
---
```

After the build, the `<meta>` element for this individual page will add your hash to the `script-src-elem` directive. Astro's automatically generated script hashes also move there, since `script-src-elem` takes precedence over `script-src` for `<script>` elements:

```html
<meta
http-equiv="content-security-policy"
content="
script-src 'self';
script-src-elem 'self' 'sha256-somehash' 'sha512-scriptHash';
style-src 'self' 'sha256-somehash';
"
>
Expand Down
15 changes: 15 additions & 0 deletions src/content/docs/en/reference/cli-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ Flags
--host <custom-address> Expose on a network IP address at <custom-address>
--open Automatically open the app in the browser on server start
--force Clear the content layer cache, forcing a full rebuild.
--ignore-lock Start the dev server even if another one is already running, without checking or writing the lock file.
--allowed-hosts Specify a comma-separated list of allowed hosts or allow any hostname.
--help (-h) See all available flags.
```
Expand Down Expand Up @@ -217,6 +218,20 @@ astro dev --background --force

<ReadMore>See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint.</ReadMore>

#### `--ignore-lock`

<p><Since v="7.1.0" /></p>

Starts the dev server without checking or writing the lock file used to detect other running dev servers. This allows a new dev server to start alongside one that's already running for the same project, instead of erroring.

```shell
astro dev --ignore-lock --port 4322
```

The new server is not tracked by `astro dev stop`, `astro dev status`, or `astro dev logs`.

When combined with `--background` (including when triggered by an AI coding agent) or `--force`, an error is thrown, as both rely on the lock file.

<h3>Subcommands</h3>

<p><Since v="7.0.0" /></p>
Expand Down
Loading
Loading