Fonts
AbsoluteJS can self-host your web fonts at build time. Add a fonts block to absolute.config.ts and your pages load fonts from your own origin, with preloads and a fallback face that keeps the layout still while they load. Pages no longer contact fonts.googleapis.com or fonts.gstatic.com.
#Configure
List each family. Give a Google Fonts family its weights and styles, or point src at font files in your project.
// absolute.config.ts
import { defineConfig } from '@absolutejs/absolute';
export default defineConfig({
reactDirectory: 'src/frontend/react',
fonts: {
families: [
{ family: 'Poppins', weights: [400, 700] },
{ family: 'Inter', weights: '100..900', styles: ['normal', 'italic'] },
{
family: 'Brand Sans',
src: [
{ path: 'src/fonts/BrandSans-Regular.woff2', weight: 400 },
{ path: 'src/fonts/BrandSans-Bold.woff2', weight: 700 }
]
}
]
}
});On each build:
build/assets/fonts/
fonts.bbeb0eba.css
poppins-latin-400-normal.3dc5d0c5.woff2
poppins-latin-700-normal.197a3cbd.woff2
brand-sans-400-normal.8909904a.woff2
brand-sans-700-normal.6f56409f.woff2#Options
Per family:
| Option | Default | Meaning |
|---|---|---|
family | required | Family name, such as 'Open Sans'. |
weights | [400] | Google Fonts weights, or one variable range such as '100..900'. |
styles | ['normal'] | 'normal' and/or 'italic'. |
subsets | ['latin'] | Google Fonts subsets to keep, such as 'latin-ext' or 'cyrillic'. Others are dropped. |
src | none | Local .woff2, .woff, .ttf or .otf files, relative to the project root, each with an optional weight and style. The family is copied from these instead of downloaded. |
display | top-level display | font-display for this family. |
preload | true | true preloads the first weight and style in the latin subset. false preloads nothing. A list picks faces. |
fallback | inferred | 'sans-serif' (Arial), 'serif' (Times New Roman) or 'monospace' (Courier New). Names containing Mono infer monospace, Serif infers serif. |
adjustFallback | true | Generate the metric-matched fallback face. |
variable | --font-<family-kebab> | CSS custom property name. |
className | font-<family-kebab> | Class that applies the family. |
On the fonts block:
| Option | Default | Meaning |
|---|---|---|
families | required | The families to build. |
display | 'swap' | Default font-display. |
fallbackToRemote | false | When a download fails, link the Google Fonts stylesheet at runtime instead of failing the build. |
cacheDirectory | .absolutejs/cache/fonts | Where downloads are kept between builds. |
injectHtml | true | Add the preloads and stylesheet to the head of HTML and HTMX pages. |
#Fonts in a Page
The build records the font stylesheet and preloads in the manifest. fontAssets(manifest) returns them as plain data, which is safe to pass as a page prop. It is empty when no fonts are configured.
For React, pass it from the route to the page and on to the fonts prop of Head. Svelte's Head component takes the same fonts prop.
// src/backend/server.ts
import { asset, fontAssets, prepare } from '@absolutejs/absolute';
import { handleReactPageRequest } from '@absolutejs/absolute/react';
const { absolutejs, manifest } = await prepare();
// ...
.get('/', () =>
handleReactPageRequest({
Page: Home,
index: asset(manifest, 'HomeIndex'),
props: {
cssPath: asset(manifest, 'HomeCSS'),
fonts: fontAssets(manifest)
}
})
)// src/frontend/react/pages/Home.tsx
import type { FontAssets } from '@absolutejs/absolute';
import { Head } from '@absolutejs/absolute/react/components';
type HomeProps = {
cssPath: string;
fonts: FontAssets;
};
export const Home = ({ cssPath, fonts }: HomeProps) => (
<html>
<Head cssPath={cssPath} fonts={fonts} title="Home" />
<body className="font-poppins">
<h1>Home</h1>
</body>
</html>
);For Vue and Angular, pass it to generateHeadElement:
import {
asset,
fontAssets,
generateHeadElement
} from '@absolutejs/absolute';
import { handleVuePageRequest } from '@absolutejs/absolute/vue';
.get('/vue', () =>
handleVuePageRequest<typeof Home>({
headTag: generateHeadElement({
fonts: fontAssets(manifest),
title: 'Home'
}),
indexPath: asset(manifest, 'HomeIndex'),
pagePath: asset(manifest, 'Home')
})
)HTML and HTMX pages need nothing. The build adds the tags to the <head> of every page, including error.html and not-found.html, ahead of the page's own stylesheets. Set injectHtml: false to add them yourself.
#Preloads
The head gets a <link rel="preload" as="font"> for each critical face, then the font stylesheet:
<link rel="preload" href="/assets/fonts/poppins-latin-400-normal.3dc5d0c5.woff2" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="/assets/fonts/brand-sans-400-normal.8909904a.woff2" as="font" type="font/woff2" crossorigin>
<link rel="stylesheet" href="/assets/fonts/fonts.bbeb0eba.css" data-absolute-fonts>By default only the first weight and style of each family is preloaded. Use preload to pick other faces or none:
fonts: {
families: [
// Preload the bold face instead of the first weight
{ family: 'Poppins', weights: [400, 700], preload: [{ weight: 700 }] },
// Preload nothing for a family used below the fold
{ family: 'Lora', weights: [400], preload: false }
]
}Nothing is inlined, so a strict style-src under secureHeaders() needs no nonce for fonts, and the default policy already allows them. A family that falls back to the remote Google Fonts stylesheet (fallbackToRemote) loads from another origin, which the default policy blocks.
#In CSS
Each family gets a variable and a class in the font stylesheet:
:root {
--font-poppins: 'Poppins', 'Poppins Fallback', sans-serif;
--font-brand-sans: 'Brand Sans', 'Brand Sans Fallback', sans-serif;
}
.font-poppins {
font-family: var(--font-poppins);
}
.font-brand-sans {
font-family: var(--font-brand-sans);
}Use the class in markup, as in className="font-poppins" above, or the variable in your own CSS:
body {
font-family: var(--font-poppins);
}
.price {
font-family: var(--font-brand-sans);
font-weight: 700;
}With Tailwind v4, the --font-poppins variable also matches the font-poppins utility.
#Fallback Metrics
While the web font loads, the browser draws text in the fallback. If the fallback is wider or taller, the page shifts when the web font arrives. For each family the build reads the font file and writes a fallback face over a local system font:
@font-face {
font-family: 'Poppins Fallback';
src: local('Arial'), local('ArialMT');
size-adjust: 114.11%;
ascent-override: 92.02%;
descent-override: 30.67%;
line-gap-override: 8.76%;
}size-adjust matches the average width of English text, and the overrides match the font's ascent, descent and line gap. The metrics come from the preloaded face, or the first latin face. Set adjustFallback: false to skip it.
#Caching & Serving
Downloads are cached under .absolutejs/cache/fonts, so later builds reuse them and work offline. If a family isn't cached and the download fails, the build stops with an error naming the family and the reason. With fallbackToRemote: true it warns instead and links the Google Fonts stylesheet for that family. The variable and class still work, without a fallback face or preload.
Font files and the font stylesheet have content-hashed names, so the production server sends them with Cache-Control: public, max-age=31536000, immutable. A changed font gets a new name, and a new build removes the old files.