fontless weekly downloads statistics

fontless

[![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![Github Actions][github-actions-src]][github-actions-href] [![Codecov][codecov-src]][codecov-href]

Magical plug-and-play font optimization for modern web applications

Features

• 🚀 Optimized font loading: Automatically loads and configures fonts with proper fallbacks and preload links. • 🔤 Multiple provider support: Google Fonts, Bunny Fonts, FontShare, FontSource, and more using unifont • 📦 Zero runtime overhead: Pure CSS solution with no JavaScript required at runtime • 📏 Metric-based fallbacks: Reduces Cumulative Layout Shift (CLS) by using font metrics from fontaine • 🔄 CSS transformation: Detects font-family usage in your CSS and injects optimized @font-face declarations • 🎯 Framework agnostic: Works with all modern frameworks (Vue, React, Solid, Svelte, Qwik, etc.)

Installation

Usage

Add the fontless plugin to your Vite configuration:

Using fonts in your CSS

Simply use fonts in your CSS as you normally would, and fontless will handle optimization:

Configuration

You can customize fontless with various options:

Entries in families that share a name configure one family. Every entry with src contributes its own @font-face. Family-level options such as preload, fallbacks, and glyphs are taken from the first entry that sets them, and the family is global if any entry sets global. If a family has both src entries and provider entries, only the src entries are used.

Category-Aware Fallbacks

Fontless uses category-aware fallback presets shared with the fontaine package. These presets provide optimized system fonts for different generic font families:

• sans-serif: Segoe UI, Helvetica Neue, Arial, Noto Sans • serif: Times New Roman, Georgia, Noto Serif • monospace: Courier New, Roboto Mono, Noto Sans Mono • cursive: Uses handwriting category fallbacks • fantasy: Uses display category fallbacks • system-ui, ui-serif, ui-sans-serif, ui-monospace: Mapped to corresponding category presets

You can override fallbacks for specific generic families in the defaults.fallbacks configuration while keeping the shared defaults for others. This ensures consistent font fallback behavior across your application and reduces cumulative layout shift (CLS).

Minification

Generated @font-face rules are minified with lightningcss, which is an optional peer dependency. Install it alongside fontless to enable minification:

Without it, the generated CSS is emitted unminified and left to the bundler's own minifier.

Glyph Subsetting

If you know a family only ever renders a fixed set of characters — a logotype, a specimen, a set of headings — set glyphs on it and fontless will reduce every file it emits for that family to those glyphs, whichever provider served it.

The subsetter is an optional peer dependency, so install it alongside fontless if you use this option:

Subsetting happens on the font file itself with harfbuzz (via subset-font), so it works for fonts from every provider as well as local files, keeps the original format and keeps a variable font's axes. Where the provider can subset server-side (Google Fonts' text= API) the glyph list is passed through to it as well, so the full file is never downloaded.

The glyph list is part of the emitted file's name, so two families sharing a source font with different glyph lists get their own file, and changing the list invalidates the cache. Fallback metrics are still read from the original font, so size-adjust and friends are unaffected. Files are emitted unchanged for families without glyphs.

[!IMPORTANT] Subsetting modifies the font file you ship. Some licences (particularly commercial and free-with-conditions ones) restrict modifying, converting or self-hosting a font, so check the licence or terms of the font you are subsetting before enabling this.

Variable Font Axes

Variable fonts expose axes beyond weight and italic, such as Recursive's casual (CASL) and monospace (MONO) axes. Set variableAxis on a family (or on defaults, for every family) to choose the values you ship. A number or string pins an axis to a single value, and a { min, max } object (or a [min, max] pair) narrows it to an inclusive range:

The request is passed to the provider first. Google Fonts serves an already-instanced file, so nothing further happens locally. For every other provider, unifont returns the variable file with a font-variation-settings descriptor, and fontless applies the axis to the file itself with subset-font, then drops the descriptor for that axis, since the axis no longer exists in the file to be varied. Values that unifont reports it left to the consumer, such as a range, are applied to the file without touching the CSS.

Applying an axis locally means subsetting the file, so it needs a glyph list: either the family's glyphs, or the characters the face's unicode-range declares. Without either, the file is emitted untouched and the font-variation-settings descriptor is kept, so the font still renders at the requested values. An axis a font file does not have is skipped, keeping any glyph subset. Because it is a subsetting pass, the licence caveat under Glyph Subsetting applies to the file you ship.

The axis values are part of the emitted file's name, so two families sharing a source font with different values get their own file, and changing a value invalidates the cache. wght and ital are left alone: they are expressed by @font-face descriptors, and pinning them would lose the other faces of the family.

[!NOTE] This option is experimental. Provider support and the option shape may change.

Preloading Fonts

Preloading is opt-in: no font is preloaded unless you ask for it. Enable it for every family with defaults.preload, or for individual families with families[].preload:…

Description from the npm listing.