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 สำหรับเอเจนต์เขียนโค้ด และไม่รับตัวเลือก
ปรับฟอนต์สำหรับ Windows และ macOS โดยไม่มี face ซีริลลิกและกรีก ผลลัพธ์เป็นข้อความเดียวกับการส่งออก 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 | ไม่สร้าง face แยกสำหรับซีริลลิกและกรีก |
-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 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;รหัสการออก (exit code)
| รหัส | ความหมาย |
|---|---|
0 | สำเร็จ |
1 | ล้มเหลว: ไฟล์ที่อ่านไม่ได้ ฟอนต์ที่ไม่ถูกต้อง กลุ่มผู้ใช้ที่ไม่ถูกต้อง |
2 | ใช้งานผิด: คำสั่งที่ไม่รู้จัก ไม่มีไฟล์ฟอนต์ ค่าตัวเลือกที่ไม่ถูกต้อง |