Where the file comes from
Since 2020 browsers partition their cache by site: Chrome since version 86, Firefox since 85, Safari even earlier. A
file from fonts.gstatic.com downloaded on one site is downloaded again on another, so the shared Google Fonts cache no
longer wins anything. Your own server saves two connections — to fonts.googleapis.com for the CSS and to
fonts.gstatic.com for the files — and the reader never contacts Google.
Take the files from Google Fonts or the Fontsource packages and host them next to the site. This site does that at
build time: Astro downloads the fonts listed in astro.config.mjs and writes their CSS itself.
// astro.config.mjs
fonts: [
{
provider: fontProviders.google(),
name: 'Golos Text',
cssVariable: '--font-golos',
weights: ['400 700'],
styles: ['normal'],
subsets: ['latin', 'cyrillic'],
fallbacks: ['sans-serif'],
},
],
weights: ['400 700'] is a range, so Astro takes the variable file. subsets says which subsets to download: Google
also offers latin-ext and cyrillic-ext for Golos, with letters of other languages, which this site doesn’t need — a
site in, say, Polish or Czech would need latin-ext. fallbacks says what to build the fallback from: for sans-serif
Astro tunes Arial. The <Font cssVariable="--font-golos" /> component puts the CSS into <head>. Below is that CSS,
without the hash Astro adds to the font’s name.
The file
@font-face {
font-family: "Golos Text";
src: url("/_astro/fonts/ddd583b46ef3047f.woff2")
format("woff2");
font-weight: 400 700;
font-style: normal;
font-display: swap;
unicode-range: U+0301, U+0400-045F, U+0490-0491,
U+04B0-04B1, U+2116;
}A variable file: font-weight: 400 700 is a range, and one 22 KB file serves both body text and bold headings; without a variable font there’d be a file per weight. unicode-range is Cyrillic: U+0400-045F covers the letters, U+2116 is “№”. The browser downloads the file only if the page has such characters.
default:font-display autounicode-range every character
@font-face {
font-family: "Golos Text";
src: url("/_astro/fonts/d911f2505890b67e.woff2")
format("woff2");
font-weight: 400 700;
font-style: normal;
font-display: swap;
unicode-range: U+0000-00FF, U+0131, U+0152-0153,
U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304,
U+0308, U+0329, U+2000-206F, U+20AC, U+2122,
U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}The same name, a different range: the browser merges the blocks into one font and takes the right file for each character. The 38 KB Latin file is needed on a Russian page too: U+0000-00FF holds the space, digits, punctuation and guillemets, U+2000-206F dashes and curly quotes. So on a Russian page Golos is two files, 60 KB.
@font-face {
font-family: "Golos Text fallback";
src: local("Arial");
size-adjust: 103.6337%;
ascent-override: 94.5638%;
descent-override: 21.2286%;
line-gap-override: 0%;
}The fallback is the system’s Arial, tuned to Golos: size-adjust stretches it by 3.6% so a paragraph takes the same width, and ascent-override and descent-override give the same line height. While Golos downloads, the text is already in its place, and the swap doesn’t move it. Astro computes the numbers from both fonts’ metrics — optimizedFallbacks, on by default.
default:size-adjust 100%ascent-override from the font
:root {
--font-golos: "Golos Text", "Golos Text fallback",
sans-serif;
--f-sans: var(--font-golos);
}
body {
font-family: var(--f-sans);
}The order: your font, the tuned fallback, the generic sans-serif in case the system lacks even Arial. Astro declares the --font-golos variable, and the site takes it through its own --f-sans: another font for body text is a one-line change in the tokens.
body {
font-synthesis: none;
}Forbids the browser from faking missing styles: bold by thickening, italic by slanting upright letters. Instead of a fake you get regular text, and you see at once which file is missing. Golos Text has no italic, and the site doesn’t use italic — so the line isn’t here.
Preloading
<link rel="preload" href="/_astro/fonts/ddd583b46ef3047f.woff2" as="font" type="font/woff2" crossorigin>
Without preload the browser learns about the file late: it parses the HTML and CSS, builds the page, and only then
sees that a paragraph needs Golos. With preload the download starts as soon as the browser reads that line in
<head>. crossorigin is needed even for your own domain: fonts are requested in CORS mode, and without the attribute
the preloaded file won’t match — the browser downloads it a second time.
Preload one or two main styles: every preload shares the connection with the CSS and the first screen’s images. Here
Russian pages preload both Golos files — a paragraph needs the Latin one from its first space — and Unbounded’s
Cyrillic, and English pages the Latin files:
<Font cssVariable="--font-golos" preload={[{ subset: 'cyrillic' }, { subset: 'latin' }]} />.
What to show while the file downloads
font-display decides what the reader sees before the file arrives. The numbers are the CSS Fonts specification’s
recommendation, and browsers may deviate from it.
| Value | While the file downloads | When the file arrives | When to use |
|---|---|---|---|
block |
text invisible, up to 3 s | swaps in | an icon font: a fallback would draw a letter instead of the icon |
swap |
the fallback right away | swaps in whenever it arrives | body text: readable at once. That’s this site, and Google Fonts with display=swap in the URL |
fallback |
the fallback after 100 ms | swaps in only if it arrived within 3 s | a jump is acceptable only in the first seconds |
optional |
the fallback after 100 ms | too late — the page stays in the fallback, and the file is used on the next page | a jump is worse than someone else’s font |
auto leaves the choice to the browser. Astro sets swap itself: the site’s astro.config.mjs doesn’t set display,
and the built CSS has swap. With a tuned fallback the swap barely moves the text.
How to check
- DevTools, the Network tab, the Font filter, a reload without cache (
Ctrl+Shift+R): on a Russian page Golos arrives as two files, about 22 and 38 KB; on an English page the 38 KB Latin file is the one preloaded. No extra subsets. - In the same place — Slow 4G throttling and a reload: the text is visible at once, and when the font swaps in, lines don’t rewrap and paragraphs don’t shift.
- Elements, Computed, the Rendered Fonts block at the bottom — for a paragraph it shows Golos Text, not Arial.
If it doesn’t work
The font is set up, but the Network tab in DevTools shows no file
- Cause
- The name in
font-familydoesn’t match the name in@font-face— even by a space — or the page has no character from theunicode-range: then the browser doesn’t request the file. - Fix
- Compare the names. In DevTools, Elements, Computed, the Rendered Fonts block at the bottom shows which font in fact drew the text.
The font file downloads twice, and the console warns about preload
- Cause
- The
<link rel=preload>has nocrossorigin. Browsers always request fonts in CORS mode, and a file preloaded without it doesn’t match. - Fix
- Add
crossorigin— even for a file from your own domain.
A font from a CDN won’t load, and the console shows a CORS error
- Cause
- The browser takes a font file from another domain only if the server answered with an
Access-Control-Allow-Originheader. - Fix
- Set the header on the CDN, or serve the file from your own domain — then CORS isn’t needed.
The fallback is tuned, but in Safari lines still shift vertically on the swap
- Cause
- Safari supports
size-adjustsince version 17, but not yetascent-override,descent-overrideandline-gap-override: width is matched, line height isn’t. - Fix
- The vertical shift in Safari stays.
preloadof the main file reduces it: the sooner the file arrives, the less text gets drawn in the fallback.