AbsoluteJS

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.

TS
// 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:

FetchDownloads the Google Fonts stylesheet and the woff2 files it names, or copies your local font files.
Self-hostWrites the files to <build>/assets/fonts/ with content-hashed names.
StylesheetWrites one linked stylesheet with the @font-face rules, using font-display: swap by default.
FallbackAdds a metric-matched fallback face per family, so text does not shift when the web font arrives.
VariablesDefines a CSS variable and a class per family.
PreloadRecords preloads for the critical faces only.
TXT
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:

OptionDefaultMeaning
familyrequiredFamily 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.
srcnoneLocal .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.
displaytop-level displayfont-display for this family.
preloadtruetrue preloads the first weight and style in the latin subset. false preloads nothing. A list picks faces.
fallbackinferred'sans-serif' (Arial), 'serif' (Times New Roman) or 'monospace' (Courier New). Names containing Mono infer monospace, Serif infers serif.
adjustFallbacktrueGenerate the metric-matched fallback face.
variable--font-<family-kebab>CSS custom property name.
classNamefont-<family-kebab>Class that applies the family.

On the fonts block:

OptionDefaultMeaning
familiesrequiredThe families to build.
display'swap'Default font-display.
fallbackToRemotefalseWhen a download fails, link the Google Fonts stylesheet at runtime instead of failing the build.
cacheDirectory.absolutejs/cache/fontsWhere downloads are kept between builds.
injectHtmltrueAdd 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.

TS
// 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)
    }
  })
)
TSX
// 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:

TS
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:

HTML
<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:

TS
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:

CSS
: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:

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:

CSS
@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.