Skip to content

feat: fonts csp #12103

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

Closed
wants to merge 7 commits into from
Closed

feat: fonts csp #12103

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d0cd25b
feat: fonts csp
florian-lefebvre Jul 31, 2025
38a8c63
Merge branch 'main' into feat/fonts-csp
florian-lefebvre Aug 13, 2025
ff7a8a2
feat: feedback
florian-lefebvre Aug 13, 2025
933804d
Merge branch 'main' into feat/fonts-csp
florian-lefebvre Aug 26, 2025
092752e
Update src/content/docs/en/reference/experimental-flags/csp.mdx
florian-lefebvre Aug 26, 2025
dada31b
Update src/content/docs/en/reference/experimental-flags/csp.mdx
florian-lefebvre Aug 26, 2025
02ab0d0
Update src/content/docs/en/reference/experimental-flags/csp.mdx
florian-lefebvre Aug 26, 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
72 changes: 72 additions & 0 deletions src/content/docs/en/reference/experimental-flags/csp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,51 @@ export default defineConfig({
});
```

### `fontDirectiveResources`

<p>

**Type:** `string[]`<br />
**Default:** `[]`<br />
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't we run into a similar tricky situation documenting something not too long ago where adding any value overrides (and removes) the default that needs to be added back in? 😅 What was that and how did we handle that?

I think what feels off here is that if you do nothing, by default you get the same result as if you added this property with 'self', right? So it's kind of like the default value is 'self' and not nothing?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed! FYI I just copied the other properties so they would also need to be updated

Suggested change
**Default:** `[]`<br />
**Default:** `["'self'"]`<br />

<Since v="5.12.7" />
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just checking whether this is releasing with the minor, or if before, then update this right before the patch release when known!

Suggested change
<Since v="5.12.7" />
<Since v="5.14.0" />

</p>

A list of valid sources for the `font-src` directive.

The `font-src` directive is handled by Astro by default, and uses the `'self'` resource. This means that fonts can only be downloaded by the current host (usually the current website).

To override the default source, you can provide a list of resources instead. 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({
experimental: {
csp: {
fontDirectiveResources: [
"'self'",
"https://fonts.cdn.example.com"
]
}
}
});
```

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

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

When using [the experimental Fonts API](/en/reference/experimental-flags/fonts/), font resources will be injected by Astro (based on [`build.assetsPrefix`](/en/reference/configuration-reference/#buildassetsprefix)) as well as style [hashes](#hashes).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just checking that this doesn't require experimental fonts to also be configured? When you say "when using the experimental fonts API" that means that all of the above is just generally true, even if not using. But now here, we are additionally specifying something that is true only when using experimental fonts, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this is not the right place for this info? But yeah basically there are 2 things:

  1. The addition to the CSP API, that can be used on its own
  2. Experimental fonts supporting CSP, which uses the new CSP API + injects styles as needed

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re: "font resources will be injected by Astro based on..." Would it be correct to say something like below, that I think is a bit more explicit?

Suggested change
When using [the experimental Fonts API](/en/reference/experimental-flags/fonts/), font resources will be injected by Astro (based on [`build.assetsPrefix`](/en/reference/configuration-reference/#buildassetsprefix)) as well as style [hashes](#hashes).
When using [the experimental Fonts API](/en/reference/experimental-flags/fonts/), Astro will apply both your [`build.assetsPrefix`](/en/reference/configuration-reference/#buildassetsprefix) configuration as well as style [hashes](#hashes) to your font resources in the `<meta>` element.

And then this prompts the question... what if I'm not using experimental fonts?? Do I have to do anything special? Will this "just work" as expected, or do I need to set something manually because I'm not using experimental fonts? Do we need an "Otherwise, you will need to...." follow up statement if someone has assets.buildPrefix set, or needs hashes to apply?

Also just checking where it says in hashes:

If you have external scripts or styles that aren’t generated by Astro, or inline scripts, this configuration option allows you to provide additional hashes to be rendered.

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

Do these now need to be extended to include fonts? Is there an analogous font line for this example? Are fonts simply an extension of styles and use their hashes, or are there separate font hashes?

(And noting that if this is only true when using experimental fonts, then, is there anything anyone needs to know in this section if they are NOT using experimental fonts?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And then this prompts the question... what if I'm not using experimental fonts?? Do I have to do anything special?

To recap:

  • You're using experimental fonts: Astro will adds things to both style.hashes and fontDirectiveResources (taking assets.buildPrefix)
  • You're not using experimental fonts: you can use fontDirectiveResources without any issues

So I'd say no.

Do these now need to be extended to include fonts?

I don't think so? Fonts only have directives, not hashes

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, but if Astro works differently when I am or am not using experimental fonts, and I probably want one particular outcome, then... how do I get that same desired result in both cases if Astro is working differently in each case? I'm not sure how they can work differently and yet "it's all good" in either case?

Like, is taking those things into consideration "good" or "bad"? (Is it more like "I probably want it consistent with how I have other things set up, and yay, using experimental fonts it's done for me so I don't have to do X, Y and Z manually when I'm not using experimental fonts!" or is this "Be careful! If you use experimental fonts, this will happen, unlike when you're not. You might have to undo it manually!")

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I think I see what you mean now. Basically, experimental fonts are dealing with font directives and style hashes, because the way it works is it injects an inline script.

Now if you're not using experimental fonts, you may be just setting fontDirectiveResources and then doing things in a css file, in which case the style hashes section already covers that.

So I guess the main difference is this:

  • When using experimental fonts, fontDirectiveResources may get things injected from assets.buildPrefix
  • When using fontDirectiveResources without experimental fonts, you have to duplicate things from assets.buildPrefix if applicable

Does that help?


## Runtime APIs

You can customize the `<meta>` element per page via runtime APIs available from the `Astro` global inside `.astro` components, or the `APIContext` type in endpoints and middleware.
Expand Down Expand Up @@ -411,3 +456,30 @@ After the build, the `<meta>` element for this individual page will add your has
"
>
```

### `insertFontResource`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this require experimental Fonts API, or work differently with or without it?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It works without experimental fonts, and works the same with or without


<p>

**Type:** `(resource: string) => void`<br />
<Since v="5.12.7" />
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same note re: version, whatever it happens to be!

</p>

Inserts a new resource to be used for the `font-src` directive.

```astro
---
Astro.insertFontResource("https://fonts.cdn.example.com");
---
```

After the build, the `<meta>` element for this individual page will add your source to the default `style-src` directive:

```html
<meta
http-equiv="content-security-policy"
content="
font-src https://fonts.cdn.example.com;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the same situation where doing this overrides and removes 'self'? If so, feels like that should also be mentioned, since it will remove the default?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, it's merged with the config so we could show 'self' if we wanted. Maybe @ematipico has an opinion on this!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so if this merges that's probably easier to document! We would just make sure that we describe it as "additive"

"
>
```