From be38646ec6472f147e3fa58306d59ba3e013b778 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Wed, 26 Aug 2026 15:20:35 +0200 Subject: [PATCH 1/3] feat(fonts): warn on invalid properties --- .../en/reference/font-provider-reference.mdx | 98 ++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/font-provider-reference.mdx b/src/content/docs/en/reference/font-provider-reference.mdx index f76bee9721db9..d63e599762dab 100644 --- a/src/content/docs/en/reference/font-provider-reference.mdx +++ b/src/content/docs/en/reference/font-provider-reference.mdx @@ -434,7 +434,7 @@ The preferred method for implementing a custom font provider is to export a func ### The font provider object -A `FontProvider` is an object containing required [`name`](#name) and [`resolveFont()`](#resolvefont) properties. It also has optional [`config`](#config), [`init()`](#init) and [`listFonts()`](#listfonts) properties available. +A `FontProvider` is an object containing required [`name`](#name) and [`resolveFont()`](#resolvefont) properties. It also has optional [`config`](#config), [`init()`](#init), [`listFonts()`](#listfonts) and [`getFontProperties()`](#getfontproperties) properties available. The `FontProvider` type accepts a generic for family [options](/en/reference/configuration-reference/#fontoptions). @@ -504,6 +504,93 @@ The project root, useful for resolving local files paths. Optional callback, used to return the list of available font names. +#### `getFontProperties()` + +

+ +**Type:** `(options: GetFontPropertiesOptions) => Awaitable`
+**Default:** `undefined`
+ +

+ +Optional callback, used to return the properties a given font family actually supports. Astro compares the values [configured for the family](/en/reference/configuration-reference/#fontname) against these properties, and logs a warning when a provider cannot serve one of them (e.g. a weight that a family does not offer). + +Return `undefined` when the family is unknown to your provider. Astro will then skip the check for that family. + +```ts title="font-provider.ts" {6-11} +import type { FontProvider } from "astro"; + +export function registryFontProvider(): FontProvider { + return { + name: "registry", + getFontProperties: ({ familyName }) => ({ + weights: ["400", "700"], + styles: ["normal", "italic"], + subsets: ["latin"], + formats: ["woff2"] + }), + // ... + }; +} +``` + +:::note +Implementing this callback is currently optional, but it will be required in Astro 8. +::: + +##### `options.familyName` + +

+ +**Type:** `string`
+

+ +The font family name, as identified by your font provider. + +##### The `FontProperties` object + +The object returned by `getFontProperties()` describes what your provider can serve for the requested family. All of its properties are optional: any property you omit is understood as "this provider does not expose that information", not as "nothing is available". + +##### `FontProperties.weights` + +

+ +**Type:** `Array | undefined`
+**Default:** `undefined`
+

+ +The [font weights](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight) available for the font family. Values are either individual weights (e.g. `"400"`), or ranges of weights for [variable fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) written as `" "` (e.g. `"100 900"`). + +##### `FontProperties.styles` + +

+ +**Type:** `Array<("normal"|"italic"|"oblique")> | undefined`
+**Default:** `undefined`
+

+ +The [font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style) available for the font family. + +##### `FontProperties.subsets` + +

+ +**Type:** `Array | undefined`
+**Default:** `undefined`
+

+ +The [font subsets](https://knaap.dev/posts/font-subsetting/) available for the font family. + +##### `FontProperties.formats` + +

+ +**Type:** `Array<("woff2"|"woff"|"otf"|"ttf"|"eot")> | undefined`
+**Default:** `undefined`
+

+ +The [font formats](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_formats) your provider can serve. This describes your provider's capabilities rather than a single family's, so some of these formats may not exist for every family. + ### Supporting a private registry The following example defines a font provider for a private registry: @@ -701,6 +788,9 @@ export function acmeFontProvider(): FontProvider { async listFonts() { return await initializedProvider?.listFonts?.(); }, + async getFontProperties({ familyName }) { + return await initializedProvider?.getFontProperties?.(familyName); + }, }; } ``` @@ -729,6 +819,9 @@ export function acmeFontProvider(config?: AcmeOptions): FontProvider { async listFonts() { return await initializedProvider?.listFonts?.(); }, + async getFontProperties({ familyName }) { + return await initializedProvider?.getFontProperties?.(familyName); + }, }; } ``` @@ -756,6 +849,9 @@ export function acmeFontProvider(): FontProvider async listFonts() { return await initializedProvider?.listFonts?.(); }, + async getFontProperties({ familyName }) { + return await initializedProvider?.getFontProperties?.(familyName); + }, }; } ``` From 915f82ebfca8ddac6e10018efe37c54267e59404 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Thu, 27 Aug 2026 10:35:51 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Chris Swithinbank Co-authored-by: Florian Lefebvre --- src/content/docs/en/reference/font-provider-reference.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/reference/font-provider-reference.mdx b/src/content/docs/en/reference/font-provider-reference.mdx index d63e599762dab..e5b4c2c2ce931 100644 --- a/src/content/docs/en/reference/font-provider-reference.mdx +++ b/src/content/docs/en/reference/font-provider-reference.mdx @@ -434,7 +434,7 @@ The preferred method for implementing a custom font provider is to export a func ### The font provider object -A `FontProvider` is an object containing required [`name`](#name) and [`resolveFont()`](#resolvefont) properties. It also has optional [`config`](#config), [`init()`](#init), [`listFonts()`](#listfonts) and [`getFontProperties()`](#getfontproperties) properties available. +A `FontProvider` is an object containing required [`name`](#name) and [`resolveFont()`](#resolvefont) properties. It also has optional [`config`](#config), [`init()`](#init), [`listFonts()`](#listfonts), and [`getFontProperties()`](#getfontproperties) properties available. The `FontProvider` type accepts a generic for family [options](/en/reference/configuration-reference/#fontoptions). @@ -513,7 +513,7 @@ Optional callback, used to return the list of available font names.

-Optional callback, used to return the properties a given font family actually supports. Astro compares the values [configured for the family](/en/reference/configuration-reference/#fontname) against these properties, and logs a warning when a provider cannot serve one of them (e.g. a weight that a family does not offer). +Optional callback, used to return the properties a given font family actually supports. Astro compares the [configuration set by a user for the family](/en/reference/configuration-reference/#fontname) against these properties, and logs a warning when a provider cannot serve one of them (e.g. a weight that a family does not offer). Return `undefined` when the family is unknown to your provider. Astro will then skip the check for that family. @@ -534,10 +534,6 @@ export function registryFontProvider(): FontProvider { } ``` -:::note -Implementing this callback is currently optional, but it will be required in Astro 8. -::: - ##### `options.familyName`

From e1f36d36ba7f95cb26e29a674d8a0e62940b03db Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Thu, 27 Aug 2026 10:36:51 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Florian Lefebvre --- src/content/docs/en/reference/font-provider-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/font-provider-reference.mdx b/src/content/docs/en/reference/font-provider-reference.mdx index e5b4c2c2ce931..b2257fd2beff1 100644 --- a/src/content/docs/en/reference/font-provider-reference.mdx +++ b/src/content/docs/en/reference/font-provider-reference.mdx @@ -545,7 +545,7 @@ The font family name, as identified by your font provider. ##### The `FontProperties` object -The object returned by `getFontProperties()` describes what your provider can serve for the requested family. All of its properties are optional: any property you omit is understood as "this provider does not expose that information", not as "nothing is available". +The object returned by `getFontProperties()` describes what your provider can serve for the requested family. ##### `FontProperties.weights`