Batch-Decompress WOFF2 to TTF in Node and CI

The core of any batch: decompress, read the output magic, write the right extension. This is exactly what the browser handler does, in Node.

import { promises as fs } from 'node:fs';
import wawoff2 from 'wawoff2';

async function extract(woff2Path) {
  const buf = await fs.readFile(woff2Path);
  const out = await wawoff2.decompress(buf); // Uint8Array
  const magic =
    (out[0] << 24) | (out[1] << 16) | (out[2] << 8) | out[3];
  const isCff = magic === 0x4f54544f; // 'OTTO'
  const ext = isCff ? 'otf' : 'ttf';
  const dest = woff2Path.replace(/\.woff2$/i, '.' + ext);
  await fs.writeFile(dest, out);
  return dest;
}

Skip fonts already extracted and newer than their source; cap parallelism so a CI runner doesn't OOM.

import { promises as fs } from 'node:fs';
import path from 'node:path';
import wawoff2 from 'wawoff2';

const dir = process.argv[2] ?? './fonts';
const LIMIT = 6;

const files = (await fs.readdir(dir))
  .filter(f => /\.woff2$/i.test(f));

let i = 0;
async function worker() {
  while (i < files.length) {
    const f = files[i++];
    const src = path.join(dir, f);
    const ttf = src.replace(/\.woff2$/i, '.ttf');
    try {
      const [s, t] = await Promise.all([
        fs.stat(src),
        fs.stat(ttf).catch(() => null),
      ]);
      if (t && t.mtimeMs >= s.mtimeMs) continue; // up to date
      const out = await wawoff2.decompress(await fs.readFile(src));
      const isCff =
        out[0]===0x4f && out[1]===0x54 &&
        out[2]===0x54 && out[3]===0x4f;
      await fs.writeFile(
        src.replace(/\.woff2$/i, isCff ? '.otf' : '.ttf'), out);
    } catch (e) {
      console.error('FAILED', f, e.message);
    }
  }
}
await Promise.all(Array.from({length: LIMIT}, worker));

Decompress production WOFF2 into TTF so a downstream PDF step can embed them. Pure Node, no Python.

- name: Extract WOFF2 -> TTF
  run: |
    npm install wawoff2
    node scripts/extract-fonts.mjs ./dist/fonts
- name: Verify every WOFF2 has a sibling sfnt
  run: |
    for w in dist/fonts/*.woff2; do
      base="${w%.woff2}"
      test -f "$base.ttf" || test -f "$base.otf" \
        || { echo "missing sfnt for $w"; exit 1; }
    done

On a paid tier, POST each font to the local runner. It decompresses with the same wawoff2 module on your machine and returns the sfnt. The response is .ttf or .otf depending on the wrapped flavour.

# Schema: GET /api/v1/tools/woff2-to-ttf
curl -sS -X POST \
  http://127.0.0.1:9789/v1/tools/woff2-to-ttf/run \
  -F 'file=@dist/fonts/Inter-Regular.woff2' \
  -o dist/fonts/Inter-Regular.ttf

# Output is the decompressed sfnt; if the source
# wrapped CFF, rename to .otf per the response.

If you already run fontTools for subsetting, it reads WOFF2 directly and saves an sfnt. brotli is required to open WOFF2.

# pip install fonttools brotli
from fontTools.ttLib import TTFont

font = TTFont('Inter-Regular.woff2')  # reads wOF2
font.flavor = None                    # drop the woff2 wrapper
font.save('Inter-Regular.ttf')        # writes raw sfnt

CFF/PostScript fonts produce an OTTO-magic buffer and must be written as .otf. A script that hardcodes .ttf for every output will mislabel CFF fonts and break strict installers. Always branch on the decompressed magic — 0x4F54544F → .otf — exactly as the browser handler does.

A WOFF, TTF, or TTC mislabelled .woff2 will not decompress. The browser tool rejects it with Expected a WOFF2 file but detected <FORMAT>; in raw npm, wawoff2.decompress throws. Wrap each decode in try/catch, log the file, and continue the batch rather than aborting the whole run.

WOFF2 has no error correction, so a single bad byte makes wawoff2.decompress throw (ConvertWOFF2ToTTF returned false in the browser). At scale this is common with flaky CDN pulls. Catch it, record the file as failed, and re-fetch from the source — partial recovery is impossible.

Each WASM decode peaks around 64 MB of WASM memory, and large CJK fonts spike higher. Unbounded Promise.all over hundreds of files can OOM a small CI box. Cap concurrency at 4–8 with a worker-pool pattern (as in the cookbook) and the memory stays flat.

Re-decompressing every font on every build is wasteful. Skip files whose target .ttf/.otf exists and is newer than the source .woff2 (or cache by source hash). Decompression is deterministic, so a cached result is always valid until the source changes.

WOFF2 normalises table order and padding, so a decompressed sfnt may not byte-match a TTF you committed earlier even though it is the same font. Do not gate CI on hash equality with an old master; compare glyph counts or render, or treat the decompressed sfnt as the new canonical artifact.

The tier ceiling (5 MB free / 50 MB Pro / 1 GB Developer) applies to the browser tool and runner API. A multi-megabyte CJK WOFF2 may need Pro or Developer. The raw wawoff2 npm package has no such limit — it is bound only by your machine's memory.

If you also subset, decide order deliberately. To shrink a web asset, subset the sfnt then re-compress with ttf-to-woff2. To recover a desktop/PDF sfnt from a deployed WOFF2, decompress here first; the result reflects whatever subset was already applied — decompression cannot restore removed glyphs.

Instantiating the WASM module has a fixed startup cost. In a long-running script the module is loaded once and reused across files, so the cost amortises; in a per-file shell-out (spawning Node per font) you pay it every time. Prefer one process that walks the directory over a process-per-file loop.

The wawoff2 Emscripten module targets modern Node. On very old Node versions the WASM instantiation or top-level await in the example may fail. Run Node 18+ (the same baseline the JAD tooling assumes) and the script behaves like the browser tool.