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 --versionCommands
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' --jsonOptions
| Option | Meaning |
|---|---|
-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-range | Add unicode-range with the glyphs each font covers. |
--no-scripts | Do not emit separate faces for Cyrillic and Greek. |
-o, --out <file> | Write the output to a file instead of stdout. |
--json | Print a JSON report instead of the file text. |
-h, --help / -v, --version | Show 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 cssCLI 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;
}Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format variablesCLI 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%;
}
:root {
--font-body: "Fira Sans", "Fira Sans Fallback", sans-serif;
}
body {
font-family: var(--font-body);
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.527;
line-height: 1.4;
}Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format tailwindCLI output
@import "tailwindcss";
@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%;
}
@theme {
--font-sans: "Fira Sans", "Fira Sans Fallback", sans-serif;
}Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nextCLI output
// Put FiraSans-Regular.ttf into ./fonts/ and the @font-face rules from the CSS export into your global CSS.
import localFont from 'next/font/local';
export const font = localFont({
src: './fonts/FiraSans-Regular.ttf',
display: 'swap',
adjustFontFallback: false,
fallback: ['Fira Sans Fallback', 'sans-serif'],
variable: '--font-body',
});Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nuxtCLI output
// Add the @font-face rules from the CSS export to a stylesheet listed in `css`.
export default defineNuxtConfig({
modules: ['@nuxt/fonts'],
fonts: {
families: [
{
name: 'Fira Sans',
src: '/fonts/FiraSans-Regular.ttf',
fallbacks: ['Fira Sans Fallback', 'sans-serif'],
},
],
},
});Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format astroCLI output
// Add the @font-face rules from the CSS export to your global styles.
import { defineConfig } from 'astro/config';
export default defineConfig({
fonts: [
{
name: 'Fira Sans',
cssVariable: '--font-body',
provider: 'local',
options: {
variants: [{ weight: 400, style: 'normal', src: ['./src/assets/fonts/FiraSans-Regular.ttf'] }],
},
fallbacks: ['Fira Sans Fallback', 'sans-serif'],
},
],
});Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format wordpressCLI output
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"typography": {
"fontFamilies": [
{
"name": "Fira Sans",
"slug": "fira-sans",
"fontFamily": "\"Fira Sans\", \"Fira Sans Fallback\", sans-serif",
"fontFace": [
{
"fontFamily": "Fira Sans",
"fontWeight": "400",
"fontStyle": "normal",
"src": [
"file:./assets/fonts/FiraSans-Regular.ttf"
]
}
]
}
]
}
}
}Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format fontaineCLI output
// Put FiraSans-Regular.ttf into ./public/fonts/ and declare their @font-face rules in your CSS. In Nuxt, put the plugin under vite.plugins.
import { FontaineTransform } from 'fontaine';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
FontaineTransform.vite({
fallbacks: {
'Fira Sans': ['Trebuchet MS'],
},
resolvePath: (id) => new URL(`./public${id}`, import.meta.url),
}),
],
});Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format preloadCLI output
<link rel="preload" href="/fonts/FiraSans-Regular.ttf" as="font" type="font/ttf" crossorigin>Command
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format loadingCLI output
const root = document.documentElement;
const done = () => root.classList.remove('fonts-loading');
root.classList.add('fonts-loading');
document.fonts.load('1em "Fira Sans"').then(done, done);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
| Code | Meaning |
|---|---|
0 | Success. |
1 | Failure: a file that cannot be read, an invalid font, an invalid audience. |
2 | Usage error: an unknown command, no font file, an invalid option value. |