webfont 12.0.0 → 12.1.1

package/NOTICE.md

@@ -43,7 +43,18 @@ If you build a font from **`.svg` icons**, you must have the right to use those
 
 Generated font files may be subject to the same restrictions as the source icons and to any third-party notices you embed via options such as `metadata` / `copyright`.
 
-### 3.2 WOFF / WOFF2 decompression
+### 3.3 TTF to webfont encoding
+
+If you **encode** one or more `.ttf` files to `eot`, `woff`, or `woff2`, you are re-wrapping font data you already hold. That operation:
+
+- does **not** make a restricted or commercial font free to use or share;
+- does **not** bypass foundry EULAs or redistribution terms;
+- preserves copyright/metadata embedded in the source TTF;
+- does **not** merge multiple weights into one file — each input yields separate outputs.
+
+**Only process fonts you are authorized to convert and redistribute** under their license.
+
+### 3.4 WOFF / WOFF2 decompression
 
 If you **decompress** one or more `.woff` or `.woff2` files (from disk or from an `http(s)` URL) to `.ttf` or `.otf`, you are extracting the **SFNT payload** inside each container. That operation:
 
@@ -54,7 +65,7 @@ If you **decompress** one or more `.woff` or `.woff2` files (from disk or from a
 
 **Only process fonts you are authorized to use and download** under their license. For remote URLs, you must also have permission to fetch and store those bytes.
 
-### 3.3 Redistribution of output
+### 3.5 Redistribution of output
 
 Publishing, shipping, or sublicensing fonts produced or extracted with webfont (in apps, websites, PDFs, design assets, npm packages, etc.) is **your responsibility**. The MIT license on webfont does **not** apply to those font files.
 
@@ -105,6 +116,7 @@ webfont depends on the following **runtime** npm packages (direct dependencies).
 | [nunjucks](https://github.com/mozilla/nunjucks) | BSD-2-Clause | CSS / SCSS / Styl templates |
 | [p-limit](https://github.com/sindresorhus/p-limit) | MIT | Concurrency limiting |
 | [resolve-from](https://github.com/sindresorhus/resolve-from) | MIT | Module resolution |
+| [svgo](https://github.com/svg/svgo) | MIT | Optional SVG optimization (`optimizeSvg`) |
 | [svg2ttf](https://github.com/fontello/svg2ttf) | MIT | SVG font → TTF |
 | [svgicons2svgfont](https://github.com/nfroidure/svgicons2svgfont) | MIT | SVG icons → SVG font |
 | [ttf2eot](https://github.com/fontello/ttf2eot) | MIT | TTF → EOT |

package/README.md

@@ -1,41 +1,47 @@
 # webfont
 
 [![NPM version](https://img.shields.io/npm/v/webfont.svg)](https://www.npmjs.org/package/webfont)
-[![Travis Build Status](https://img.shields.io/travis/itgalaxy/webfont/master.svg?label=build)](https://travis-ci.org/itgalaxy/webfont)
-[![Build status](https://ci.appveyor.com/api/projects/status/a8absovr2r44w1oc?svg=true)](https://ci.appveyor.com/project/evilebottnawi/webfont)
+[![Node.js CI](https://github.com/itgalaxy/webfont/actions/workflows/pr.yml/badge.svg)](https://github.com/itgalaxy/webfont/actions/workflows/pr.yml)
 
-Generator of fonts from SVG icons, with a separate mode to **decompress** WOFF/WOFF2 containers to the TTF or OTF inside.
+Generator of fonts from SVG icons, with separate modes to **encode** TTF to web formats and **decompress** WOFF/WOFF2 containers to the TTF or OTF inside.
 
 See **[FEATURES.md](./FEATURES.md)** for the canonical capability list (what is stable, in progress, or planned).
 
 **Legal / licensing:** [NOTICE.md](./NOTICE.md) — font copyright, disclaimers, attribution guidelines, and third-party library notices.
 
+**Troubleshooting:** [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — common errors on the current release (including [icons that lose detail after export](./TROUBLESHOOTING.md#icon-details-missing-after-export) due to `fill-rule: evenodd`, #175).
+
+**Migration:** [MIGRATION.md](./MIGRATION.md) — what changed between versions and how to upgrade.
+
 ## Features
 
 - **SVG icon pipeline** (default): `.svg` icons → `svg`, `ttf`, `eot`, `woff`, `woff2` (not `otf`);
+- **TTF encoding**: one or more `.ttf` files → `ttf` (pass-through), `eot`, `woff`, and/or `woff2` (auto-detected — no extra flag);
 - **Webfont decompression**: one `.woff` or `.woff2` file → `ttf` and/or `otf` matching the **embedded SFNT flavor** (decompress only — not TTF ↔ OTF transcoding);
 - Config files: `JavaScript`, `JSON`, or `YAML` via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig);
 - Built-in and custom CSS templates (`css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/));
-- CLI and programmatic API;
+- CLI and programmatic API (**Node.js build time only** — see [TROUBLESHOOTING](./TROUBLESHOOTING.md#cant-resolve-fs-webpack--react--vite-client-bundle));
 - [Webpack plugin](https://github.com/itgalaxy/webfont-webpack-plugin).
 
 ## Input modes
 
-webfont runs one of two pipelines depending on matched input files. They cannot be mixed in a single run.
+webfont runs one of three pipelines depending on matched input files. They cannot be mixed in a single run.
 
 | Mode | Input | Outputs | Notes |
 |------|--------|---------|--------|
 | **SVG icons** | One or more `.svg` files | `svg`, `ttf`, `eot`, `woff`, `woff2` | Default. Builds TrueType via `svg2ttf`. **`otf` is rejected** — use `ttf`. |
+| **TTF encoding** | One or more `.ttf` files | `ttf`, `eot`, `woff`, and/or `woff2` per input | Auto-detected. Default when SVG-pipeline `formats` are still configured: `woff` + `woff2`. No templates. |
 | **Webfont decompress** | One or more `.woff` / `.woff2` paths, globs, or `http(s)` URLs | `ttf` and/or `otf` per input | One output file per source (basename from filename; collisions get `-woff`/`-woff2`). Not a single merged font. |
 
 **Not supported today**
 
 - Renaming or re-wrapping without matching the real outline format (e.g. requesting `otf` when the WOFF2 holds TrueType).
 - Converting TTF to OTF (or OTF to TTF) — use [FontForge](https://fontforge.org/) or similar.
-- Templates, `glyphTransformFn`, or merged multi-weight SFNT output in webfont decompress mode.
+- `.otf` as input for webfont encoding (TrueType `.ttf` only today).
+- Templates, `glyphTransformFn`, `glyphContentTransformFn`, or merged multi-weight SFNT output in TTF encoding or webfont decompress mode.
 - Globs that match extension-less or unsupported files together with fonts (the run fails instead of silently ignoring extras).
 
-Every matched path must end in `.svg`, `.woff`, or `.woff2`. See [FEATURES.md](./FEATURES.md) for test-backed criteria.
+Every matched path must end in `.svg`, `.ttf`, `.woff`, or `.woff2`. See [FEATURES.md](./FEATURES.md) for test-backed criteria.
 
 ### Font licensing
 
@@ -69,14 +75,36 @@ Full details, disclaimers, community attribution guidelines, and third-party lib
 
 ## Installation
 
+Requires **Node.js** >= 24.14.0 (aligned with `svgicons2svgfont@16`). CI tests on Node 24.x and 26.x. Install as a dev dependency and run at **build time** (CLI, npm script, or bundler plugin) — not from browser/React client bundles.
+
 ```shell
 npm install --save-dev webfont
 ```
 
 ## Usage
 
+Node.js only — do not import from client-side app code ([#198](https://github.com/itgalaxy/webfont/issues/198)).
+
+### Import (ESM and CommonJS)
+
+Use the **named export** — required for native ESM and recommended since webfont **10+**:
+
 ```js
-import webfont from "webfont";
+import { webfont } from "webfont";
+```
+
+CommonJS:
+
+```js
+const { webfont } = require("webfont");
+```
+
+`import webfont from "webfont"` is callable in versions that ship the ESM build (**12.x+**), where the default export is the `webfont` function itself ([#618](https://github.com/itgalaxy/webfont/issues/618)). On older releases the default import resolved to the whole `module.exports` object and threw `TypeError: webfont is not a function` under `"type": "module"`. The named import remains the recommended form for new code. See the [migration notes](./docs/migration/issue-0618-esm-default-import.md).
+
+### Basic example
+
+```js
+import { webfont } from "webfont";
 
 webfont({
   files: "src/svg-icons/**/*.svg",
@@ -96,7 +124,7 @@ webfont({
 or
 
 ```js
-const webfont = require("webfont").default;
+const { webfont } = require("webfont");
 
 webfont({
   files: "src/svg-icons/**/*.svg",
@@ -113,10 +141,34 @@ webfont({
   });
 ```
 
+### TTF encoding examples
+
+```js
+import { webfont } from "webfont";
+
+// Single local TTF → WOFF + WOFF2 (default when formats unset)
+const encoded = await webfont({
+  files: "path/to/font.ttf",
+});
+
+// Explicit formats
+const subset = await webfont({
+  files: "path/to/font.ttf",
+  formats: ["woff2"],
+});
+
+// Batch: multiple TTF files in one run
+const batch = await webfont({
+  files: ["fonts/Inter-Regular.ttf", "fonts/Inter-Bold.ttf"],
+  formats: ["woff", "woff2"],
+});
+// batch.transcodedFonts → [{ source, woff, woff2 }, …]
+```
+
 ### Webfont decompress examples
 
 ```js
-import webfont from "webfont";
+import { webfont } from "webfont";
 
 // Single local file
 const one = await webfont({
@@ -145,9 +197,10 @@ const remote = await webfont({
 - Type: `string` | `array`
 - Description: A file glob, or array of file globs. Ultimately passed to [fast-glob](https://github.com/mrmlnc/fast-glob) to figure out what files you want to get.
 - **SVG mode**: one or more `.svg` icon paths or globs (default pipeline).
+- **TTF encoding mode**: one or more `.ttf` paths or globs.
 - **Webfont decompress mode**: one or more `.woff` / `.woff2` paths, globs, or `https://…` URLs (see [`formats`](#formats) and [Input modes](#input-modes)).
-- Do not mix `.svg` with `.woff` / `.woff2` in the same run.
-- Every matched file must have a supported extension (`.svg`, `.woff`, `.woff2`); extension-less files such as `LICENSE` are not ignored when matched by a broad glob.
+- Do not mix `.svg`, `.ttf`, and `.woff` / `.woff2` in the same run.
+- Every matched file must have a supported extension (`.svg`, `.ttf`, `.woff`, `.woff2`); extension-less files such as `LICENSE` are not ignored when matched by a broad glob.
 - `node_modules` and `bower_components` are always ignored.
 
 #### `configFile`
@@ -170,18 +223,22 @@ const remote = await webfont({
 #### `formats`
 
 - Type: `array`
-- Default: `['svg', 'ttf', 'eot', 'woff', 'woff2']` (SVG input). For WOFF/WOFF2 input, defaults to `['ttf']` when SVG-pipeline formats are still configured.
+- Default: `['svg', 'ttf', 'eot', 'woff', 'woff2']` (SVG input). For TTF input, defaults to `['woff', 'woff2']` when SVG-pipeline formats are still configured. For WOFF/WOFF2 input, defaults to `['ttf']` when SVG-pipeline formats are still configured.
 - Possible values: `svg`, `ttf`, `otf`, `eot`, `woff`, `woff2`
 - Description: Font file types to generate.
   - **SVG input**: `svg`, `ttf`, `eot`, `woff`, `woff2` only. **`otf` is not supported** (pipeline uses TrueType outlines).
+  - **TTF input**: `ttf`, `eot`, `woff`, and/or `woff2` only. **`svg` and `otf` are not produced** in this mode.
   - **WOFF/WOFF2 input**: `ttf` and/or `otf` only — must match the decompressed SFNT flavor inside the file (not arbitrary transcoding). `eot`, `woff`, `woff2`, and `svg` are not produced in this mode.
 - CLI: pass `-f` / `--formats` as a JSON array (for example `'["woff2"]'`) or as a comma-separated list (for example `woff2` or `svg, ttf, woff2`). Invalid format names throw an error.
+- API and config files: `formats` must be an array of the values above; unknown names (for example `icon`) throw before the pipeline runs.
 
 #### `template`
 
-- Type: `string`
+- Type: `string` or `string[]`
 - Default: `null`
-- Possible values: `css`, `scss`, [`styl`](https://github.com/itgalaxy/webfont/pull/164/) (feel free to contribute more).
+- Possible values: `css`, `scss`, `styl`, `html`, `json` (feel free to contribute more), or a path to a custom `.njk` template.
+- Pass an **array** to generate multiple outputs in one run (for example `['html', 'scss']` for preview + styles, #158).
+- CLI: pass `-t` / `--template` as a single name, a JSON array (`'["html","scss"]'`), or a comma-separated list (`html,scss`).
 - Note: If you want to use a custom template use this option pass in a path `string` like this:
 
   ```js
@@ -221,14 +278,69 @@ const remote = await webfont({
 #### `templateFontName`
 
 - Type: `string`
-- Default: Gets is from `fontName` if not set, but you can specify any value.
-- Description: Template font family name you want.
+- Default: Same as [`fontName`](#fontname) when not set.
+- Description: CSS `font-family` name emitted by built-in templates (`fontFamily` in Nunjucks context). Output **font files** are always named after `fontName` (for example `icons-a.woff2`); built-in templates reference those files with `{{ fontName }}` in `url(...)` while `font-family` uses `{{ fontFamily }}` ([#331](https://github.com/itgalaxy/webfont/issues/331)).
+
+#### `templateCacheString`
+
+- Type: `string`
+- Default: `Date.now()` at generation time
+- Description: Query string appended to font `url(...)` values in built-in templates (before optional `&v=` hash). Use a fixed value (for example `v=1`) when you only need manual cache busting; pair with [`addHashInFontUrl`](#addhashinfonturl) for automatic content-based busting.
+
+#### `addHashInFontUrl`
+
+- Type: `boolean`
+- Default: `false`
+- Description: When `true` and a built-in `template` is used, append `&v=<md5>` to each font URL in the generated CSS/SCSS/Styl. The hash is derived from the SVG font output — it changes only when icon data changes. **Output filenames stay** `fontName.woff2`, `fontName.scss`, etc. (stable `@import` paths).
+- CLI: `--addHashInFontUrl`
+- Addresses browser cache issues without renaming font files on every build ([#125](https://github.com/itgalaxy/webfont/issues/125)).
+
+**Example — stable `webfont.scss`, cache-busted font URLs:**
+
+```shell
+webfont "icons/*.svg" -d dist/icons -t scss --addHashInFontUrl
+```
+
+```js
+import { webfont } from "webfont";
+
+await webfont({
+  files: "src/icons/**/*.svg",
+  fontName: "webfont",
+  template: "scss",
+  templateFontPath: "./fonts/",
+  addHashInFontUrl: true,
+});
+// Writes dist/icons/webfont.scss and dist/icons/webfont.woff2 (fixed names).
+// SCSS contains url("./fonts/webfont.woff2?...&v=<md5>") — hash updates when icons change.
+```
+
+Do **not** use `Math.random()` in `fontName` — that renames both font files and the stylesheet on every run.
+
+#### `unicodeRange`
+
+- Type: `boolean | string`
+- Default: `false` (omit `unicode-range` from built-in templates)
+- Description: When `true` and a built-in `template` is used, emit a `unicode-range` declaration in `@font-face` so the browser can load only the icon font that owns the code points on the page. With the default `startUnicode` (`0xEA01`), the range is derived from the minimum and maximum allocated code points (for example `U+EA01-EA03`). Pass a CSS value string (for example `U+EA01-EAFF`) to override the computed range. Set to `false` to omit the rule (default).
+- CLI: `--unicode-range` to enable auto-computed range
+- Helps when **multiple icon fonts** share a page ([#322](https://github.com/itgalaxy/webfont/issues/322)) — each `@font-face` can declare which private-use code points it owns so the browser skips downloading fonts that cannot render the glyphs in use.
+- **Ligature trade-off:** computed `unicode-range` covers **private-use code points only** (ligature names are ignored when building the range). If you type icon names with OpenType ligatures (`font-feature-settings: "liga"`), a PUA-only `unicode-range` prevents the browser from applying the icon font to ASCII letters, so ligatures **do not render**. Prefer class + codepoint icons in production when `unicode-range` is enabled, or leave `unicodeRange` at the default `false` if you rely on ligature names.
 
 #### `ligatures`
 
+- Type: `boolean`
+- Default: `false` (ligature glyphs are **not** added unless you opt in)
+- Description: When `true`, each glyph gets a second unicode entry: the icon name with hyphens replaced by underscores (for example `phone-call` → `phone_call`). Browsers can map that character sequence to the icon glyph when OpenType ligatures are enabled (`font-feature-settings: "liga"`).
+- CLI: `--ligatures` to enable ligature glyphs in the font.
+- **Why off by default:** large icon sets (thousands of glyphs) produce huge GSUB tables. **Firefox on Windows** (DirectWrite) can hang or slow dramatically when ligatures are enabled ([#558](https://github.com/itgalaxy/webfont/issues/558)). Prefer **class + private-use codepoint** CSS for MDI-scale fonts. webfont prints a warning when glyph count exceeds 2000 with ligatures enabled.
+
+#### `templateFontLigatures`
+
 - Type: `boolean`
 - Default: `true`
-- Description: Turn on/off adding ligature unicode
+- Description: When `true` and the built-in **`html`** preview template is used, the generated CSS enables `font-feature-settings: "liga"` on the **Ligature** section (`#icon-ligatures`) so ligature names render as icons instead of invisible/missing glyphs. If you also enable [`unicodeRange`](#unicoderange), the HTML template **omits** `unicode-range` on `@font-face` while ligature preview is on (ligature strings are ASCII; a PUA-only `unicode-range` would block the icon font for those characters). Set to `false` if you inject your own ligature CSS.
+- CLI: `--no-template-font-ligatures` to omit the CSS rule.
+- Requires [`ligatures`](#ligatures) enabled (`--ligatures` / `ligatures: true`). Class-based icons (`.font-name-icon::before` with a private-use codepoint) work without this option.
 
 #### `glyphTransformFn`
 
@@ -238,7 +350,7 @@ const remote = await webfont({
 - Example:
 
   ```js
-  import webfont from "webfont";
+  import { webfont } from "webfont";
 
   webfont({
     files: "src/svg-icons/**/*.svg",
@@ -260,6 +372,69 @@ const remote = await webfont({
     });
   ```
 
+#### `glyphContentTransformFn`
+
+- Type: `function`
+- Default: `null`
+- Description: Transform each SVG glyph **before** font generation (SVG pipeline only). Use this hook to preprocess SVGs — for example stroke-based icons converted to filled paths. **webfont does not bundle preprocessors**; install tools such as [`svg-outline-stroke`](https://github.com/elrumordelaluz/outline-stroke) in **your** project and call them from this function (see [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md)). `glyphTransformFn` only changes metadata; this hook receives the full `GlyphData` (`contents`, `srcPath`, optional `metadata`) and must return the new SVG string.
+- Example (stroke icons, #144 — **install `svg-outline-stroke` in your app**, not in webfont):
+
+  ```js
+  import outlineStroke from "svg-outline-stroke";
+  import { webfont } from "webfont";
+
+  await webfont({
+    files: "src/svg-icons/**/*.svg",
+    glyphContentTransformFn: async (glyph) => outlineStroke(glyph.contents),
+  });
+  ```
+
+  For better trace quality with `svg-outline-stroke`, use a larger `width` / `height` / `viewBox` on the source SVG (see the library README).
+
+#### `optimizeSvg`
+
+- Type: `boolean`
+- Default: `false`
+- Description: When `true`, run a **conservative** [SVGO](https://github.com/svg/svgo) pass on each SVG **after** diagnostics and **before** `glyphContentTransformFn`. Removes editor cruft (comments, metadata, doctype) without rewriting paths or removing `viewBox`. Does **not** convert stroke-only artwork to fills — pair with [`glyphContentTransformFn`](#glyphcontenttransformfn) for stroke icons ([#327](https://github.com/itgalaxy/webfont/issues/327), [#724](https://github.com/itgalaxy/webfont/issues/724)).
+- CLI: `--optimize-svg`
+- Optional: `svgoConfig` — SVGO `Config` object; when `plugins` is set, it replaces the built-in conservative plugin list.
+
+  ```js
+  import { webfont } from "webfont";
+
+  await webfont({
+    files: "src/icons/**/*.svg",
+    optimizeSvg: true,
+    glyphContentTransformFn: async (glyph) => {
+      // optional: stroke-to-fill after SVGO cleanup
+      return glyph.contents;
+    },
+  });
+  ```
+
+#### `svgTools` (alpha)
+
+- Type: `{ diagnose?: boolean; onMessage?: (message: string) => void }`
+- Default: `undefined` (disabled)
+- Description: **Alpha.** Scan SVG sources for icon-font incompatibilities before font generation (SVG pipeline only). Does **not** modify SVGs — use [`glyphContentTransformFn`](#glyphcontenttransformfn) to preprocess (for example stroke-to-fill with [`svg-outline-stroke`](https://github.com/elrumordelaluz/outline-stroke), installed in your project). See [ADR 0011](docs/adr/0011-no-svg-outline-stroke-dependency.md).
+  - **`diagnose`:** log warnings for `fill-rule: evenodd`, stroke-only paths (`fill="none"` + `stroke`), `<use>` symbol references ([#612](https://github.com/itgalaxy/webfont/issues/612)), and poorly supported elements (`<line>`, `<polyline>`, `<clipPath>`). Results are also returned on `result.svgDiagnostics` when enabled.
+  - **`onMessage`:** optional sink for diagnostic log lines (tests, custom UIs).
+- CLI: `--svg-diagnose` (alpha).
+- Example:
+
+  ```js
+  import { webfont } from "webfont";
+
+  const result = await webfont({
+    files: "src/icons/**/*.svg",
+    svgTools: { diagnose: true },
+  });
+
+  console.log(result.svgDiagnostics);
+  ```
+
+  See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — “Icon details missing after export”.
+
 #### `metadataProvider`
 
 - Type: `function`
@@ -267,7 +442,7 @@ const remote = await webfont({
 - Description: Custom callback to resolve glyph metadata for each source file. Receives the file path and a Node-style callback `(error, metadata)` where `metadata` is `{ name: string, unicode?: string | string[] }`. When omitted, webfont uses its default metadata reader.
 
   ```js
-  import webfont from "webfont";
+  import { webfont } from "webfont";
 
   webfont({
     files: "src/svg-icons/**/*.svg",
@@ -492,6 +667,10 @@ If you're using cross-env:
 
             Tell me everything!.
 
+        --svg-diagnose
+
+            (Alpha) Scan SVG icons for icon-font incompatibilities and log warnings.
+
     For "svgicons2svgfont":
 
         --font-id

package/dist/browser.js

@@ -0,0 +1,4 @@
+//#region src/browser.ts
+var e = () => Promise.reject(/* @__PURE__ */ Error("webfont is Node.js-only (requires fs, globby, and other Node built-ins). Run it at build time via the CLI, a Node script, or the webfont-webpack-plugin — do not import it from client-side React/Vue code. See TROUBLESHOOTING.md (Can't resolve 'fs')."));
+//#endregion
+export { e as default, e as webfont };