feat: fonts csp #12103

florian-lefebvre · 2025-07-31T14:43:25Z

Description (required)

Document new APIs that allow fonts to work with csp

Related issues & labels (optional)

Closes #
Suggested label:

For Astro version: `???`. See astro PR #14154.

(Doesn't require a minor, but won't be ready for 5.13.0 so will release sometime after)

astrobot-houston · 2025-07-31T14:43:54Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/reference/experimental-flags/csp.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

netlify · 2025-07-31T14:43:57Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`02ab0d0`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68adea004ccb0f00086602fa
😎 Deploy Preview	https://deploy-preview-12103--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

sarah11918

Hey Florian! Just a couple of quick initial questions here to start!

sarah11918 · 2025-07-31T19:04:52Z

src/content/docs/en/reference/experimental-flags/csp.mdx

+<p>
+
+**Type:** `string[]`<br />
+**Default:** `[]`<br />


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?

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

Suggested change

**Default:** `[]`<br />

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

sarah11918 · 2025-07-31T19:05:00Z

src/content/docs/en/reference/experimental-flags/csp.mdx

+<meta
+  http-equiv="content-security-policy"
+  content="
+    font-src https://fonts.cdn.example.com;


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?

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

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

florian-lefebvre · 2025-08-26T13:05:08Z

@sarah11918 this is ready for review!

sarah11918

OK, here is all my confusion for you, Florian! 😅

src/content/docs/en/reference/experimental-flags/csp.mdx

sarah11918 · 2025-08-26T14:16:48Z

src/content/docs/en/reference/experimental-flags/csp.mdx

+
+**Type:** `string[]`<br />
+**Default:** `["'self'"]`<br />
+<Since v="5.12.7" />


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" />

sarah11918 · 2025-08-26T14:23:59Z

src/content/docs/en/reference/experimental-flags/csp.mdx

+</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).


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?

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

The addition to the CSP API, that can be used on its own

Experimental fonts supporting CSP, which uses the new CSP API + injects styles as needed

src/content/docs/en/reference/experimental-flags/csp.mdx

sarah11918 · 2025-08-26T14:46:22Z

src/content/docs/en/reference/experimental-flags/csp.mdx

+</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).


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?)

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

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!")

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?

sarah11918 · 2025-08-26T14:46:50Z

src/content/docs/en/reference/experimental-flags/csp.mdx

+<p>
+
+**Type:** `(resource: string) => void`<br />
+<Since v="5.12.7" />


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

sarah11918 · 2025-08-26T14:47:15Z

src/content/docs/en/reference/experimental-flags/csp.mdx

@@ -411,3 +456,30 @@ After the build, the `<meta>` element for this individual page will add your has
  "
 >
 ```
+
+### `insertFontResource`


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

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

src/content/docs/en/reference/experimental-flags/csp.mdx

Co-authored-by: Sarah Rainsberger <[email protected]>

src/content/docs/en/reference/experimental-flags/csp.mdx

feat: fonts csp

d0cd25b

florian-lefebvre mentioned this pull request Jul 31, 2025

feat(fonts): csp withastro/astro#14154

Closed

1 task

sarah11918 reviewed Jul 31, 2025

View reviewed changes

sarah11918 added add new content Document something that is not in docs. May require testing, confirmation, or affect other pages. merge-on-release Don't merge this before the feature is released! (MQ=approved but WAIT for feature release!) labels Jul 31, 2025

sarah11918 added this to the 5.13.0 milestone Aug 1, 2025

sarah11918 added minor-release For the next minor release; in the milestone, "merge queue" when approved by Sarah! and removed minor-release For the next minor release; in the milestone, "merge queue" when approved by Sarah! labels Aug 5, 2025

sarah11918 removed this from the 5.13.0 milestone Aug 8, 2025

florian-lefebvre marked this pull request as draft August 13, 2025 08:16

florian-lefebvre added 3 commits August 13, 2025 10:21

Merge branch 'main' into feat/fonts-csp

38a8c63

feat: feedback

ff7a8a2

Merge branch 'main' into feat/fonts-csp

933804d

florian-lefebvre marked this pull request as ready for review August 26, 2025 13:05

sarah11918 reviewed Aug 26, 2025

View reviewed changes

florian-lefebvre and others added 2 commits August 26, 2025 18:01

Update src/content/docs/en/reference/experimental-flags/csp.mdx

092752e

Co-authored-by: Sarah Rainsberger <[email protected]>

Update src/content/docs/en/reference/experimental-flags/csp.mdx

dada31b

florian-lefebvre commented Aug 26, 2025

View reviewed changes

src/content/docs/en/reference/experimental-flags/csp.mdx Outdated Show resolved Hide resolved

Update src/content/docs/en/reference/experimental-flags/csp.mdx

02ab0d0

florian-lefebvre closed this Aug 27, 2025

florian-lefebvre deleted the feat/fonts-csp branch August 27, 2025 15:45

	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.

Uh oh!

feat: fonts csp #12103

feat: fonts csp #12103

Uh oh!

Conversation

florian-lefebvre commented Jul 31, 2025 • edited by sarah11918 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description (required)

Related issues & labels (optional)

For Astro version: ???. See astro PR #14154.

Uh oh!

astrobot-houston commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

netlify bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

florian-lefebvre commented Aug 26, 2025

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

florian-lefebvre commented Jul 31, 2025 •

edited by sarah11918

Loading

For Astro version: `???`. See astro PR #14154.

astrobot-houston commented Jul 31, 2025 •

edited

Loading

netlify bot commented Jul 31, 2025 •

edited

Loading