Skip to content
fontstay.dev
Source code on GitHub
Theme
Vision simulation

For design checks; does not correct colour vision.

Reading aids

CLI and Node library

The fontstay package is the fit engine of this site without the browser: a command-line tool and a Node library that read font files and print the same @font-face rules and exports as the app. It needs no DOM and makes no network requests, so it fits build pipelines and CI.

Install

The package is not published to npm yet. It requires Node 24 or newer; build it from a checkout of the repository. The examples below write fontstay for node packages/fontstay/dist/bin.js.

git clone https://github.com/fogrew/fontstay.dev.git
cd fontstay.dev
pnpm install
pnpm cli:build
node packages/fontstay/dist/bin.js --version

Commands

fit reads one or more font files (WOFF2, WOFF, TTF, OTF) and prints the fallback CSS. Several files are merged into one stylesheet, as in the app. mcp starts an MCP server on stdio for coding agents and takes no options.

Fit a font for Windows and macOS without the Cyrillic and Greek faces. The output is the same text as the CSS export in the app.

$ fontstay fit font.woff2 --systems windows,macos --no-scripts
@font-face {
  font-family: "Source Sans Pro Fallback";
  src: local("Arial"), local("ArialMT");
  size-adjust: 93.697%;
  ascent-override: 105.0194%;
  descent-override: 29.1365%;
  line-gap-override: 0%;
}

body {
  font-family: "Source Sans Pro", "Source Sans Pro Fallback", sans-serif;
  /* Safari has no vertical overrides: match the x-height and fix the line box */
  font-size-adjust: 0.48;
  line-height: 1.4;
}

.fonts-loading {
  letter-spacing: -0.0003em;
  word-spacing: -0.0025em;
}
fontstay fit Inter.woff2 -o fallbacks.css
fontstay fit regular.woff2 bold.woff2 --format tailwind
fontstay fit font.woff2 -a 'last 2 chrome versions, os windows' --json

Options

OptionMeaning
-s, --systems <list>Systems to fit: windows, macos, ios, android, linux, chromeos. Default: every system with at least 1% share in the audience.
-a, --audience <query>Browserslist query, optionally with “os <system>” and “not os <system>” parts. Default: baseline widely available.
-f, --format <format>Output format, see below. Default: css.
-k, --kind <kind>Generic family of the fallbacks: sans-serif, serif, monospace or cursive. Default: detected from the font.
--locale <en|ru>Frequency profile of the fit: en or ru. Default: en.
--unicode-rangeAdd unicode-range with the glyphs each font covers.
--no-scriptsDo not emit separate faces for Cyrillic and Greek.
-o, --out <file>Write the output to a file instead of stdout.
--jsonPrint a JSON report instead of the file text.
-h, --help / -v, --versionShow the help or the version.

Output formats

--format takes one of these values. They match the export formats of the app and start from the same fit.

Run this command for each format using the sample Fira Sans font. Output shown is from the built CLI.

Command

fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format css

CLI output

@font-face {
  font-family: "Fira Sans Fallback";
  src: local("Trebuchet MS"), local("TrebuchetMS");
  size-adjust: 100.3942%;
  ascent-override: 93.1328%;
  descent-override: 26.3959%;
  line-gap-override: 0%;
}

body {
  font-family: "Fira Sans", "Fira Sans Fallback", sans-serif;
  /* Safari has no vertical overrides: match the x-height and fix the line box */
  font-size-adjust: 0.527;
  line-height: 1.4;
}

.fonts-loading {
  letter-spacing: -0.0019em;
}

Output and reports

The file text goes to stdout. With --json the CLI prints a report instead, with the keys file (the output in the chosen format), fonts (family, detected kind, glyph coverage and the fallback picked per system for each font), shares (audience share of each system, in percent), systems, uncovered (systems in the audience without a fallback font) and audience (the resolved query and the number of matching browsers). The shares depend on the browser data at the time of the run.

Warnings go to stderr, so they never end up in the output: a font whose fallbacks share less than 90% of its glyphs, and systems without any fallback font. With --out the CLI also reports the written file on stderr.

Node library

fit takes font bytes and fitFiles reads files. Both return the CSS, the output in the requested format, a report per font and the audience shares. Failures throw FitRunError (invalid-audience, no-systems, no-fit) or FontParseError (for example invalid-font). The types are in index.d.ts.

import { fit, fitFiles } from 'fontstay';
import { readFile } from 'node:fs/promises';

const { css, fonts, shares } = await fit({
  fonts: [{ fileName: 'font.woff2', data: await readFile('font.woff2') }],
  audience: 'defaults',
  systems: ['windows', 'macos'],
});

const tailwind = (await fitFiles(['font.woff2'], { format: 'tailwind' })).file.text;

Exit codes

CodeMeaning
0Success.
1Failure: a file that cannot be read, an invalid font, an invalid audience.
2Usage error: an unknown command, no font file, an invalid option value.

Set up the MCP server