Automate TTF-to-WOFF2 Conversion in Your Build Pipeline

Same library the browser tool uses. Walk source fonts, compress, write WOFF2. Idempotent on mtime so unchanged fonts are skipped.

// scripts/woff2.mjs  — npm i wawoff2
import { readdir, readFile, writeFile, stat } from 'node:fs/promises';
import { compress } from 'wawoff2';

const SRC = 'src/fonts', OUT = 'public/fonts';
for (const f of await readdir(SRC)) {
  if (!/\.(ttf|otf)$/i.test(f)) continue;
  const out = `${OUT}/${f.replace(/\.(ttf|otf)$/i, '.woff2')}`;
  const src = `${SRC}/${f}`;
  const fresh = await stat(out).then(s => s.mtimeMs, () => 0);
  if ((await stat(src)).mtimeMs <= fresh) continue;   // up to date
  await writeFile(out, await compress(await readFile(src)));
  console.log('woff2 →', out);
}

prebuild runs automatically before npm run build (and next build). Commit the WOFF2 or gitignore it — your call.

{
  "scripts": {
    "prebuild": "node scripts/woff2.mjs",
    "build": "next build"
  }
}

The C++ reference encoder. Fast for large batches; produces byte-for-byte the canonical WOFF2.

# one font
woff2_compress src/fonts/Inter-Regular.ttf   # → Inter-Regular.woff2

# whole folder
for f in src/fonts/*.ttf; do woff2_compress "$f"; done
mv src/fonts/*.woff2 public/fonts/

If the runner is paired, POST the font to the local endpoint; it returns WOFF2. No Python, no native build. ttf-to-woff2 takes no options.

curl -sS -X POST http://127.0.0.1:9789/v1/tools/ttf-to-woff2/run \
  -F 'files=@src/fonts/Inter-Regular.ttf' \
  -o public/fonts/Inter-Regular.woff2

Run the converter, then fail the build if any output exceeds a budget or if a generated WOFF2 wasn't committed.

- name: Generate WOFF2
  run: node scripts/woff2.mjs
- name: Fail if a WOFF2 was missing
  run: git diff --exit-code public/fonts/
- name: Enforce size budget
  run: |
    for f in public/fonts/*.woff2; do
      SIZE=$(stat -c%s "$f")
      echo "$f = $SIZE bytes"
      test "$SIZE" -le 153600   # fail if any weight > 150 KB
    done

fonttools/woff2_compress need Python or a C++ toolchain that minimal CI images lack. The wawoff2 npm package (pure JS/WASM) or the JAD runner's HTTP API both avoid that — same WOFF2 output, no apt-get. This is the most common reason teams switch engines.

If your glob accidentally includes *.woff2, you'll decompress and re-compress for ~0% gain. Restrict the source glob to *.{ttf,otf} and treat WOFF2 as the build output, not an input.

WOFF2 compresses the bytes you keep; it doesn't drop glyphs. A full CJK or icon font stays large after compression. Add a subsetting step (pyftsubset/hb-subset, or the Font Subsetter runner endpoint) before the WOFF2 step. See Automate font subsetting in your build pipeline.

Re-compressing every font on every build is wasteful. Skip fonts whose source mtime/hash is unchanged (as the Node example does), or only run the step on production builds so local dev stays fast.

If you .gitignore the WOFF2 but the deploy pipeline doesn't run the generator, the served @font-face 404s. Either commit the generated files, or ensure the deploy job runs the same converter before bundling. The git diff --exit-code guard catches the committed-files variant.

Variable fonts compress to WOFF2 with the same step and no special handling — fvar/gvar survive the wrap, so axes still work. If you want a smaller static instance instead, instance first (Variable Font Freezer or fonttools varLib.instancer), then WOFF2-compress.

Neither the browser tool nor a naive script handles a TrueType Collection directly. Split it into individual TTF/OTF faces (otc2otf, fonttools) before the WOFF2 step, or your converter throws Unsupported font format: ttc.

Even a perfect build can be undone by a server returning text/plain for .woff2. Add a deploy-side check (or static-host config) ensuring font/woff2. The bytes are still valid WOFF2 — verify with the Font Format Identifier.