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 Fantasticon

Fantasticon builds an icon-font kit from an SVG directory (CSS, preview, JSON, and TypeScript types). The shared table, what webfont adds, and a short option map are in webfont and Fantasticon.

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-create

webfont 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. For Grunt, copy the documented custom task into your project (#771, ADR 0014).

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	✅ (docs)	✅ (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.