fontless

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

# npm
npm install fontless

# pnpm
pnpm install fontless

Usage

Add the fontless plugin to your Vite configuration:

// vite.config.js / vite.config.ts
import { defineConfig } from 'vite'
import { fontless } from 'fontless'

export default defineConfig({
  plugins: [
    // ... other plugins
    fontless()
  ],
})

Using fonts in your CSS

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

/* Your CSS */
.google-font {
  font-family: "Poppins", sans-serif;
}

.bunny-font {
  font-family: "Aclonica", sans-serif;
}

Configuration

You can customize fontless with various options:

fontless({
  // Configure available providers
  providers: {
    google: true,          // Google Fonts
    bunny: true,           // Bunny Fonts
    fontshare: true,       // FontShare
    fontsource: true,      // FontSource
    // Disable a provider
    adobe: false
  },

  // Provider priority order
  priority: ['google', 'bunny', 'fontshare'],

  // Default font settings
  defaults: {
    preload: true, // also accepts { subsets: ['latin'], styles: ['normal'] } or a filter function
    weights: [400, 700],
    styles: ['normal', 'italic'],
    // Fallbacks use category-aware presets from fontaine
    // Override specific generic families as needed
    fallbacks: {
      'sans-serif': ['Arial', 'Helvetica Neue'],
      // serif, monospace, cursive, fantasy, system-ui, etc. use shared defaults
    }
  },

  // Custom font family configurations
  families: [
    // Configure a specific font
    {
      name: 'Poppins',
      provider: 'google',
      weights: [300, 400, 600]
    },
    // Ship only the glyphs this family needs
    {
      name: 'Cabinet Grotesk',
      glyphs: 'Handgloves & 0123'
    },
    // Manual font configuration, with one entry per face
    {
      name: 'CustomFont',
      src: [{ url: '/fonts/custom-font-regular.woff2', format: 'woff2' }],
      weight: 400
    },
    {
      name: 'CustomFont',
      src: [{ url: '/fonts/custom-font-black.woff2', format: 'woff2' }],
      weight: 900
    }
  ],

  // Asset configuration
  assets: {
    prefix: '/assets/_fonts'
  },

  // Where font metadata and downloaded fonts are cached between builds, defaulting to
  // `node_modules/.cache/fontless/meta`. Accepts a directory (resolved from the Vite
  // root), `{ dir }`, a storage instance such as `unstorage` for a custom driver, or `false` to
  // disable persistent caching.
  cache: '.cache/fonts',

  // Experimental features
  experimental: {
    disableLocalFallbacks: false
  }
})

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:

pnpm add -D lightningcss

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:

pnpm add -D subset-font

fontless({
  // apply to every family
  defaults: { glyphs: 'Handgloves & 0123' },
  families: [
    // a string of text...
    { name: 'Cabinet Grotesk', glyphs: 'Handgloves & 0123' },
    // ...an explicit list of characters...
    { name: 'Erode', glyphs: ['H', 'a', 'n', 'd'] },
    // ...or unicode ranges, in the same syntax as `unicode-range`
    { name: 'Satoshi', glyphs: ['U+0020-007E', 'U+2018-201D', 'U+2026'] },
  ],
})

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:

fontless({
  families: [
    {
      name: 'Recursive',
      variableAxis: {
        CASL: [1],
        MONO: [{ min: 0, max: 1 }],
      },
    },
  ],
})

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:

fontless({
  // preload one font face per family
  defaults: { preload: true },
  // ...or configure specific families
  families: [
    { name: 'Poppins', preload: true },
    // preload every face matching all of the descriptors given
    { name: 'Inter', preload: { subsets: ['latin'], styles: ['normal'] } },
    // or filter faces individually
    { name: 'Roboto', preload: (family, font) => font.style === 'normal' },
  ],
})

preload: true picks a single face per family, preferring, in order: your first configured format, the first subset in the family's subsets option, upright over italic, and the weight closest to 400.

Where no subsets are configured, or none of them match the faces a provider returns, the pick is biased toward Basic Latin: the face whose unicode-range covers U+0041 wins, because no provider reports which subset a site primarily renders. If your site is not primarily latin-script, order subsets to put your subset first, or select faces yourself with the callback form.

For Vite SPA, the selected preload fonts are injected into the HTML, apart from the first vite dev render, where the stylesheets have not been transformed yet.

For SSR meta-frameworks which don't rely on transformIndexHtml plugin hook, you need to manually render preload links on the server. Fontless provides fontless/runtime module for server to access the necessary data for preload links generation, for example:

• Vanilla

import { preloads } from "fontless/runtime";

function renderHtml() {
  const renderedPreloads = preloads
    .map(
      (attrs) =>
        `<link rel="${attrs.rel}" as="${attrs.as}" href="${attrs.href}" crossorigin="${attrs.crossorigin}">`,
    )
    .join("\n");
  return `\
<html>
  <head>
    ${renderedPreloads}
  </head>
  <body>
    ...
  </body>
</html>
`;
}

• Qwik

import { preloads } from "fontless/runtime"

export const RouterHead = component$(() => {
  return (
    <>
      {preloads.map((l) => (
        <link key={l.href} {...l} />
      ))}
      ...
    </>
  )
})

• React

import { preloads } from 'fontless/runtime'

function Layout() {
  return (
    <html lang="en">
      <head>
        {preloads.map(({crossorigin, ...attrs}) => (
          <link
            key={attrs.href}
            {...attrs}
            crossOrigin={crossorigin}
          />
        ))}
        ...
      </head>
      <body>
        ...
      </body>
    </html>
  )
}

• SvelteKit

If preloads is an empty array, either no preload option is enabled, or a configured subset list or filter function matched no font faces, or fontless/runtime was not transformed by the plugin. In the last case, check that fontless() is in your Vite config and that fontless/runtime is not externalised.

<script lang="ts">
	import { preloads } from "fontless/runtime";
</script>

<svelte:head>
	<link rel="icon" href={favicon} />
	{#each preloads as attrs}
		<link {...attrs} />
	{/each}
</svelte:head>

Global Font Faces

Some fonts are never referenced from CSS that Fontless can see, so there is no usage site to inject their @font-face at: a family used only from inline styles, from a canvas, or from a third-party widget. Mark those families global and their @font-face is emitted regardless of usage.

fontless({
  families: [
    { name: 'Inter', global: true },
  ],
})

For Vite SPA the declarations are inlined into a <style> tag in <head>, rather than linked as a stylesheet, so the browser learns about the family without waiting for another request. Unlike preloads, this works on the first vite dev render, as global families are resolved from your config rather than discovered from stylesheets.

Any usage of the family that does appear in CSS still gains the metric-override fallback families, so global does not cost you the layout-shift protection.

For SSR meta-frameworks, fontless/runtime exposes the same declarations as a string:

import { globalFontFaces } from 'fontless/runtime'

function Head() {
  return <style dangerouslySetInnerHTML={{ __html: globalFontFaces }} />
}

An empty string means no families are configured with global: true, that none of them resolved to a font, or that fontless/runtime was not transformed by the plugin.

DevTools

When Vite DevTools is enabled, Fontless adds a Fonts panel to its dock during vite dev. For every resolved family it shows the faces with their file sizes, which faces are preloaded, the stylesheets using the family, the generated @font-face CSS, and a preview of each metric-override fallback laid over the web font. Families that are used but could not be resolved, and warnings logged while resolving, are listed too.

export default defineConfig({
  devtools: true,
  plugins: [fontless()],
})

Pass devtools: false to fontless() to leave the panel out.

The panel is a devframe, so other devframe hosts can mount it too. fontless/devtools exports the definition along with callbacks to pass to createResolver and transformCSS:

import { createResolver, transformCSS } from 'fontless'
import { createFontlessDevframe } from 'fontless/devtools'

const { definition, exposeFont, exposeUsage, exposeWarning } = createFontlessDevframe()

const resolve = await createResolver({
  /* ... */
  exposeFont,
  logger: { warn: (message) => { console.warn(message); exposeWarning(message) } },
})
await transformCSS({ /* ... */ exposeUsage }, code, id)
// mount `definition` in a devframe host, e.g. `kit.install(definition)`

createFontlessDevframe() also accepts options to fit the panel into its host:

createFontlessDevframe({
  // `exposeUsage` is passed to `transformCSS` for every stylesheet, so families
  // that no stylesheet uses any more can be marked as unused
  reportsUsage: true,
  ui: {
    // accent colour; defaults to the host's brand colour, where it sets one
    primaryColor: '#00dc82',
    // how the `families` option is written in your config, for hints
    familiesOption: 'fonts.families',
    // documentation linked from the panel
    docsURL: 'https://fonts.nuxt.com',
  },
})

fontless/devtools requires devframe to be installed for its types.

How It Works

Fontless works by:

1. Scanning your CSS files for font-family declarations
2. Resolving fonts through various providers (Google, Bunny, etc.)
3. Generating optimized @font-face declarations with proper metrics
4. Adding fallback fonts with correct metric overrides to reduce CLS
5. Automatically downloading and managing font assets

💻 Development

• Clone this repository
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Made with ❤️

Published under MIT License.