CLI と Node ライブラリ
fontstay パッケージは、このサイトの調整エンジンからブラウザーを取り除いたものです。フォントファイルを読み取り、アプリと同じ @font-face ルールとエクスポートを出力するコマンドラインツールと Node ライブラリです。DOM は不要でネットワークリクエストも行わないため、ビルドパイプラインや CI に向いています。
インストール
パッケージはまだ npm に公開されていません。Node 24 以降が必要です。リポジトリのチェックアウトからビルドしてください。以下の例では、node packages/fontstay/dist/bin.js を fontstay と書いています。
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 は 1 つ以上のフォントファイル(WOFF2、WOFF、TTF、OTF)を読み取り、フォールバック CSS を出力します。複数のファイルは、アプリと同じく 1 つのスタイルシートにまとめられます。mcp は、コーディングエージェント向けに stdio で MCP サーバーを起動し、オプションは取りません。
キリル文字とギリシャ文字のフェイスを除いて、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 広く利用可能。 |
-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 cssCLI の出力
@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 variablesCLI の出力
@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 tailwindCLI の出力
@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 nextCLI の出力
// 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 nuxtCLI の出力
// 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 astroCLI の出力
// 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 wordpressCLI の出力
{
"$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 fontaineCLI の出力
// 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 preloadCLI の出力
<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 loadingCLI の出力
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 を付けると、CLI は代わりにレポートを出力します。キーは file(選択した形式の出力)、fonts(フォントごとのファミリー、検出された種類、グリフのカバー率、システムごとに選ばれたフォールバック)、shares(システムごとの対象ユーザーのシェア、単位は %)、systems、uncovered(対象ユーザーにいるが、フォールバックフォントのないシステム)、audience(解決されたクエリと、一致したブラウザー数)です。シェアは、実行時点のブラウザーデータに左右されます。
警告は stderr に出力されるため、出力に混ざることはありません。フォールバックと共有するグリフが 90% 未満のフォント、およびフォールバックフォントのないシステムが対象です。--out を付けた場合、CLI は書き込んだファイルについても 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 | 使い方のエラー:不明なコマンド、フォントファイルの指定なし、オプションの値が無効。 |