Migration guide
What changed between webfont releases and how to update your setup.
See also packages/webfont/CHANGELOG.md for the full release history.
Where entries live
Each change has its own file under docs/migration/ — not a growing section in this document. That keeps parallel PRs from conflicting on the same markdown file. Browse that folder (files are named issue-0569-cli-round.md) for the change that affects you.
Adding or updating an entry? See docs/migration/README.md for naming, the merge-conflict-safe PR workflow, and the required entry structure.
Migrating from other tools
Comparisons with older or adjacent projects live here so README.md stays focused on installing and using webfont.
Comparison with webfonts
webfont (this project) is sometimes confused with the older, unmaintained webfonts package (note the trailing s). webfonts last shipped around 2015 and requires a Java runtime (it bundles batik-ttf2svg, sfnt2woff, and ttf2eot). webfont is pure JavaScript, actively maintained, and does everything the useful parts of webfonts did — plus SVG-icon fonts, WOFF2, decompression, templates, and a Node.js API.
| Capability | webfont (this project) | webfonts (uipoet/webfonts) |
|---|---|---|
| Maintained | ✅ | ❌ (last release ~2015) |
| Runtime | Pure JS (Node.js) | Node.js + Java |
| SVG icons → font | ✅ (default pipeline) | ❌ |
| TTF input → web formats | ✅ | ✅ |
Output: woff2 (Brotli) | ✅ | ❌ |
Output: woff / eot | ✅ | ✅ |
Output: svg font | ✅ (-f svg, opt-in) | ✅ |
| Choose which formats to emit | ✅ (-f / formats) | ❌ (always woff + eot + svg) |
| WOFF/WOFF2 → TTF/OTF decompression | ✅ | ❌ |
| Node.js / programmatic API | ✅ (webfont()) | ❌ (CLI only) |
| CSS / SCSS / Styl templates | ✅ | ❌ (manual @font-face snippet) |
| Config files (cosmiconfig) | ✅ | ❌ |
.otf as a source | ❌ (tracking #767) | ❌ (requested) |
Command-line equivalents
# webfonts (unmaintained): converts a directory of TTFs, always emits woff + eot + svg
webfonts fonts/ -o dist/
# webfont: pick your formats explicitly (woff2 recommended for the web)
webfont "fonts/*.ttf" -f woff2,woff,eot,svg -d dist --dest-createwebfont adds woff2 (much smaller than the legacy formats), lets you emit only what you ship, and needs no Java toolchain.
Comparison with grunt-webfont
grunt-webfont is the classic "SVG → webfont" Grunt plugin (~1.1k★, MIT). It is archived (read-only since 2021, last release v1.2.0), and its best-fidelity output relies on a native FontForge binary (its pure-node engine can't do ligatures). webfont is a framework-agnostic, actively maintained, pure-JS library and CLI: it does everything grunt-webfont generated — plus TTF encoding, WOFF/WOFF2 decompression, more templates, and programmatic hooks. The one thing grunt-webfont has that webfont doesn't is native Grunt wiring (tracked in #771); you can already drive webfont() from a small custom Grunt task.
| Capability | webfont (this project) | grunt-webfont (sapegin/grunt-webfont) |
|---|---|---|
| Maintained | ✅ | ❌ (archived 2021, v1.2.0) |
| Runtime | Node API + CLI (any build tool) | Grunt task only |
| Engine | Pure JS (svg2ttf) | node or FontForge binary |
| SVG icons → font | ✅ | ✅ |
| Output formats | svg, ttf, eot, woff, woff2 | eot, woff2, woff, ttf, svg |
| TTF input → web formats | ✅ | ❌ |
| WOFF/WOFF2 → TTF/OTF decompression | ✅ | ❌ |
| Stylesheets | css, scss, styl, html, json + custom Nunjucks, multiple per run | css, sass, scss, less, stylus + custom |
| CSS syntax presets (BEM / Bootstrap) | ❌ (use a custom template) | ✅ |
data:uri embedding in CSS | ❌ | ✅ (embed) |
Autohinting (ttfautohint) | via ttfPostProcess hook (external, opt-in) | built-in (autoHint) |
| Ligatures | ✅ (opt-in) | ✅ (FontForge engine only) |
| Codepoint map persistence | ❌ | ✅ (codepointsFile) |
| Programmatic API | ✅ (webfont()) | ❌ (Grunt only) |
| SVG diagnostics | ✅ (alpha) | ❌ |
| Grunt integration | ⏳ (#771) | ✅ (native) |
If you only need the generation that grunt-webfont did, webfont is a maintained, FontForge-free replacement. If you specifically need BEM/Bootstrap CSS presets or data:uri embedding today, use a custom template in the configuration guide.