CLI e biblioteca para Node
O pacote fontstay é o motor de ajuste deste site sem o navegador: uma ferramenta de linha de comando e uma biblioteca Node que leem arquivos de fontes e imprimem as mesmas regras @font-face e exportações do aplicativo. Não precisa de DOM nem de rede, por isso serve para pipelines de build e CI.
Instalação
O pacote ainda não foi publicado no npm. Requer Node 24 ou superior; compile-o a partir de uma cópia do repositório. Nos exemplos abaixo, fontstay significa 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 --versionComandos
fit lê um ou mais arquivos de fonte (WOFF2, WOFF, TTF, OTF) e imprime o CSS de reserva. Vários arquivos são combinados numa só folha de estilos, como no aplicativo. mcp inicia um servidor MCP via stdio para agentes de programação e não aceita opções.
Ajuste uma fonte para Windows e macOS sem as faces cirílica e grega. A saída é o mesmo texto da exportação CSS do aplicativo.
$ 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' --jsonOpções
| Opção | Significado |
|---|---|
-s, --systems <list> | Sistemas a ajustar: windows, macos, ios, android, linux, chromeos. Padrão: todos os sistemas com pelo menos 1% de participação no público. |
-a, --audience <query> | Consulta do Browserslist, opcionalmente com partes «os <system>» e «not os <system>». Padrão: baseline widely available. |
-f, --format <format> | Formato de saída, veja abaixo. Padrão: css. |
-k, --kind <kind> | Família genérica das fontes de reserva: sans-serif, serif, monospace ou cursive. Padrão: detectada a partir da fonte. |
--locale <en|ru> | Perfil de frequência do ajuste: en ou ru. Padrão: en. |
--unicode-range | Adiciona unicode-range com os glifos que cada fonte cobre. |
--no-scripts | Não gera faces separadas para cirílico e grego. |
-o, --out <file> | Grava a saída num arquivo em vez de stdout. |
--json | Imprime um relatório JSON em vez do texto do arquivo. |
-h, --help / -v, --version | Mostra a ajuda ou a versão. |
Formatos de saída
--format aceita um destes valores. Eles correspondem aos formatos de exportação do aplicativo e partem do mesmo ajuste.
Execute este comando para cada formato usando a fonte Fira Sans de exemplo. A saída mostrada vem da CLI compilada.
Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format cssSaída da CLI
@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;
}Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format variablesSaída da CLI
@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;
}Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format tailwindSaída da CLI
@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;
}Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nextSaída da CLI
// 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',
});Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nuxtSaída da CLI
// 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'],
},
],
},
});Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format astroSaída da CLI
// 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'],
},
],
});Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format wordpressSaída da CLI
{
"$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"
]
}
]
}
]
}
}
}Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format fontaineSaída da CLI
// 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),
}),
],
});Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format preloadSaída da CLI
<link rel="preload" href="/fonts/FiraSans-Regular.ttf" as="font" type="font/ttf" crossorigin>Comando
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format loadingSaída da CLI
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);Saída e relatórios
O texto do arquivo vai para stdout. Com --json é impresso um relatório com as chaves file (a saída no formato escolhido), fonts (família, tipo detectado, cobertura de glifos e a fonte de reserva escolhida por sistema para cada fonte), shares (participação de cada sistema no público, em porcentagem), systems, uncovered (sistemas do público sem fonte de reserva) e audience (a consulta resolvida e o número de navegadores correspondentes). As participações dependem dos dados de navegadores no momento da execução.
Os avisos vão para stderr, por isso nunca aparecem na saída: uma fonte cujas reservas compartilham menos de 90% dos glifos e sistemas sem nenhuma fonte de reserva. Com --out, a ferramenta também informa o arquivo gravado em stderr.
Biblioteca para Node
fit recebe os bytes da fonte e fitFiles lê arquivos. Ambas retornam o CSS, a saída no formato pedido, um relatório por fonte e as participações do público. Falhas lançam FitRunError (invalid-audience, no-systems, no-fit) ou FontParseError (por exemplo invalid-font). Os tipos estão em 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;Códigos de saída
| Código | Significado |
|---|---|
0 | Sucesso. |
1 | Falha: um arquivo ilegível, uma fonte inválida ou um público inválido. |
2 | Erro de uso: um comando desconhecido, nenhum arquivo de fonte ou um valor de opção inválido. |