CLI и библиотека для Node
Пакет fontstay — это движок подбора этого сайта без браузера: консольная утилита и библиотека для Node, которые читают файлы шрифтов и выдают те же правила @font-face и форматы экспорта, что и приложение. Им не нужны DOM и сеть, поэтому они подходят для сборки и CI.
Установка
Пакет пока не опубликован в npm. Нужен Node 24 или новее; соберите его из клона репозитория. В примерах ниже fontstay означает 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Команды
fit читает один или несколько файлов шрифтов (WOFF2, WOFF, TTF, OTF) и выводит CSS запасных шрифтов. Несколько файлов объединяются в один стиль, как в приложении. mcp запускает MCP-сервер на stdio для coding-агентов и не принимает опций.
Подбор шрифта для Windows и macOS без кириллических и греческих начертаний. Вывод совпадает с CSS-экспортом приложения.
$ 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Опции
| Опция | Значение |
|---|---|
-s, --systems <list> | Системы для подбора: windows, macos, ios, android, linux, chromeos. По умолчанию — все системы с долей не менее 1% в аудитории. |
-a, --audience <query> | Запрос Browserslist, при необходимости с частями «os <system>» и «not os <system>». По умолчанию: baseline widely available. |
-f, --format <format> | Формат вывода, см. ниже. По умолчанию: css. |
-k, --kind <kind> | Родовое семейство запасных шрифтов: sans-serif, serif, monospace или cursive. По умолчанию определяется по шрифту. |
--locale <en|ru> | Частотный профиль подбора: en или ru. По умолчанию: en. |
--unicode-range | Добавить unicode-range с глифами, которые покрывает каждый шрифт. |
--no-scripts | Не создавать отдельные начертания для кириллицы и греческого. |
-o, --out <file> | Записать вывод в файл вместо stdout. |
--json | Вывести JSON-отчёт вместо текста файла. |
-h, --help / -v, --version | Показать справку или версию. |
Форматы вывода
--format принимает одно из этих значений. Они совпадают с форматами экспорта приложения и строятся на одном и том же подборе.
Запустите эту команду для каждого формата с образцом шрифта Fira Sans. Показан вывод собранной CLI.
Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format cssВывод 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;
}Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format variablesВывод 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;
}Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format tailwindВывод 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;
}Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nextВывод 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',
});Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nuxtВывод 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'],
},
],
},
});Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format astroВывод 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'],
},
],
});Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format wordpressВывод 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"
]
}
]
}
]
}
}
}Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format fontaineВывод 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),
}),
],
});Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format preloadВывод CLI
<link rel="preload" href="/fonts/FiraSans-Regular.ttf" as="font" type="font/ttf" crossorigin>Команда
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format loadingВывод 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);Вывод и отчёты
Текст файла выводится в stdout. С --json выводится отчёт с ключами file (вывод в выбранном формате), fonts (семейство, определённый тип, покрытие глифов и запасной шрифт по каждой системе для каждого шрифта), shares (доля каждой системы в аудитории, в процентах), systems, uncovered (системы аудитории без запасного шрифта) и audience (разобранный запрос и число подходящих браузеров). Доли зависят от данных о браузерах на момент запуска.
Предупреждения идут в stderr и не попадают в вывод: шрифт, у запасных которого общих глифов меньше 90%, и системы без запасных шрифтов. С --out утилита также сообщает в stderr о записанном файле.
Библиотека для Node
fit принимает байты шрифта, fitFiles читает файлы. Обе возвращают CSS, вывод в запрошенном формате, отчёт по каждому шрифту и доли аудитории. При сбоях выбрасываются FitRunError (invalid-audience, no-systems, no-fit) или FontParseError (например, invalid-font). Типы лежат в 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;Коды завершения
| Код | Значение |
|---|---|
0 | Успех. |
1 | Сбой: файл не читается, шрифт повреждён, неверная аудитория. |
2 | Ошибка использования: неизвестная команда, нет файла шрифта, неверное значение опции. |