Generate Font Fingerprints in Your Build Pipeline

Walks src/fonts, reproduces all four Fingerprinter fields, copies hashed files into dist/fonts, and writes the manifest. Output is byte-identical to the browser tool.

import { readFileSync, writeFileSync, readdirSync, mkdirSync, copyFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { join, basename, extname } from 'node:path';

const SRC = 'src/fonts', OUT = 'dist/fonts';
mkdirSync(OUT, { recursive: true });
const manifest = {};

for (const name of readdirSync(SRC)) {
  if (!/\.(ttf|otf|woff2?|)$/i.test(name)) continue;
  const buf = readFileSync(join(SRC, name));
  const hex = createHash('sha256').update(buf).digest('hex');
  const short = hex.slice(0, 8);
  const ext = extname(name).slice(1) || 'woff2';
  const stem = basename(name, extname(name));
  const hashedFilename = `${stem}.${short}.${ext}`;
  const b64 = createHash('sha256').update(buf).digest('base64');
  copyFileSync(join(SRC, name), join(OUT, hashedFilename));
  manifest[name] = {
    hash: hex, shortHash: short, hashedFilename,
    sriAttribute: `integrity="sha256-${b64}"`, fileSize: buf.length,
  };
}
writeFileSync('fonts.manifest.json', JSON.stringify(manifest, null, 2));

One entry per source font. Templates read hashedFilename for src URLs and sriAttribute for preload integrity.

{
  "Inter-Regular.woff2": {
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "shortHash": "e3b0c442",
    "hashedFilename": "Inter-Regular.e3b0c442.woff2",
    "sriAttribute": "integrity=\"sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=\"",
    "fileSize": 30696
  }
}

Run the fingerprinter before the bundle so hashed assets and the manifest exist when the build references them.

{
  "scripts": {
    "prebuild": "node scripts/fingerprint-fonts.mjs",
    "build": "next build"
  }
}

A tiny emitter that turns the manifest into the deployable CSS, so the src URLs always match the hashed files in dist/.

import { readFileSync, writeFileSync } from 'node:fs';
const m = JSON.parse(readFileSync('fonts.manifest.json', 'utf8'));
const css = Object.entries(m).map(([src, e]) =>
`@font-face {\n  font-family: "${src.split('-')[0]}";\n  font-display: swap;\n  src: url("/fonts/${e.hashedFilename}") format("woff2");\n}`
).join('\n\n');
writeFileSync('dist/fonts.css', css);

If you already run the @jadapps/runner for other font steps, POST the font to the local tool endpoint and read back the same JSON the browser tool produces.

# pair once, then per file:
curl -s -X POST \
  http://127.0.0.1:9789/v1/tools/font-fingerprinter/run \
  -F 'file=@src/fonts/Inter-Regular.woff2' \
  | jq '{sha256, short_hash, cache_busted_filename, sri_attribute}'
# the option schema (empty for this tool):
#   GET /api/v1/tools/font-fingerprinter

If your script parses the font (opentype.js, fonttools) and re-serialises before hashing, the bytes differ from the file on disk and your hash will not match the JAD Fingerprinter, shasum, or your CDN's ETag. Hash the raw fs.readFileSync buffer exactly as the tool does. Parse only for analysis steps, never for fingerprinting.

If a previous build step regenerates the WOFF2 (e.g. a subsetter that embeds a timestamp or uses a different encoder version), the font's bytes change every build and so does the hash — fonts.manifest.json churns on every commit. Pin the encoder/subsetter version and disable timestamp embedding so unchanged inputs produce unchanged outputs. Then the manifest is stable and re-runs are true no-ops.

Fonts are binary; a .gitattributes rule that applies text=auto / EOL normalisation to font files will silently corrupt them and change every hash. Mark fonts as binary: *.woff2 binary (and the same for ttf/otf/woff). This is a frequent cause of 'the hash changed but I didn't touch the font'.

A loose extension regex can sweep in .DS_Store, .map, or a stray .txt, hashing non-fonts into the manifest. The script hashes whatever it reads — it does not validate the format. Tighten the filter to \.(ttf|otf|woff|woff2)$ and, if you need certainty, gate on font-format-identifier before fingerprinting.

If Inter-Regular.woff2 and a duplicated body.woff2 share a sha256, they are byte-identical — you're shipping the same file twice under two names. Use the hash as a dedupe key in the manifest to ship one physical asset and alias the rest. SHA-256 collisions are not a concern in practice.

The @jadapps/runner binds to loopback 127.0.0.1:9789. If CI tries the runner endpoint without the runner running (or paired), the POST fails with connection refused. For headless CI, prefer the hand-rolled crypto.createHash script — it has no runtime dependency and produces identical output.

Like the tool, the script defaults ext to woff2 when a filename has no extension. If an upstream step strips extensions, your hashed filename ends .<short8>.woff2 regardless of the real format. Preserve extensions through the pipeline, or set ext explicitly from the detected format.

Decide once: either commit fonts.manifest.json (so a review sees every hash change explicitly — good for supply-chain auditing, see the supply-chain guide) or .gitignore it as a build artifact. Mixing the two causes spurious diffs when CI regenerates a committed file. Pick the auditable path if integrity matters.