@skelekit/font

Optimal fonts for static sites — zero external runtime dependencies.

@skelekit/font is a post-build tool that:

1. Scans your static site for font references.
2. Downloads them locally if they're external (e.g., Google Fonts).
3. Subsets each font to only the characters actually used.
4. Generates accurate fallback system fonts to eliminate layout shift (CLS).
5. Outputs both WOFF and WOFF2 variants.
6. Rewrites your CSS with optimized @font-face rules.

Built entirely with JavaScript — no Python, no native bindings, no external binaries.

Perfect for static site generators like Eleventy, Hugo, Jekyll, and more.

Installation

npm install @skelekit/font

Usage

skelekit-font --site path/to/site

For additional options:

skelekit-font --help

Command-Line Options

• --site=path/to/site: Specify the directory containing your site files.
• --verbose: Enable verbose logging.
• --whitelist-chars=chars: Specify a string of characters to be included in the font subset even if they are not found in the HTML source. For example, --whitelist-chars=abc will ensure that the characters 'a', 'b', and 'c' are included in the subset.

Features

Layout Shift Prevention

Skelekit Font automatically adds a system font fallback for each web font that matches the original font's metrics. This prevents layout shifts during font loading by:

1. Creating a fallback font-face using Arial with the same metrics as your web font
2. Automatically applying this fallback to all font-family declarations
3. Using CSS size-adjust and metric overrides to match the system font exactly

For example, if you have:

.title {
    font-family: "My Font";
}

It will be transformed to:

.title {
    font-family: "My Font", "My Font override";
}

@font-face {
    font-family: "My Font override";
    src: local("Arial");
    ascent-override: 95%;
    descent-override: 25%;
    line-gap-override: normal;
    size-adjust: 100%;
}

This ensures text maintains the same dimensions and layout both before and after the web font loads.

Limitations

• Only processes built, static HTML/CSS/JS — does not support dynamic font loading via JS
• Does not currently support variable fonts (coming soon)
• Font subsetting accuracy may be reduced if text is injected via JS
• Only supports fonts loaded from Google, Bunny CDN, or local.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

License

This project is licensed under the MIT License - see the LICENSE file for details.