Automate Font Base64 Encoding in Your Build Pipeline

The core operation: read, encode single-line, wrap. toString('base64') never line-wraps, so the output survives lightningcss.

import { readFileSync } from "node:fs";

function toDataUri(path, mime) {
  const b64 = readFileSync(path).toString("base64"); // single line
  return `data:${mime};base64,${b64}`;
}

const uri = toDataUri("src/fonts/Brand.woff2", "font/woff2");
console.log(`url("${uri}") format("woff2")`);

Read the built CSS, replace each local .woff2 reference with its inlined data URI, write to dist/. Keeps source CSS untouched.

import { readFileSync, writeFileSync } from "node:fs";
import { resolve, dirname } from "node:path";

const cssPath = "dist/styles.css";
let css = readFileSync(cssPath, "utf8");

css = css.replace(/url\("([^"]+\.woff2)"\)/g, (_, ref) => {
  const file = resolve(dirname(cssPath), ref);
  const b64 = readFileSync(file).toString("base64");
  return `url("data:font/woff2;base64,${b64}")`;
});

writeFileSync(cssPath, css);

Inline only the fonts you actually want inline (e.g. the critical Regular), leave everything else as external requests for cacheability.

const INLINE = new Set(["Brand-Regular.woff2"]);

css = css.replace(/url\("([^"]+\.woff2)"\)/g, (m, ref) => {
  const name = ref.split("/").pop();
  if (!INLINE.has(name)) return m;            // leave external
  const b64 = readFileSync(resolve("dist", ref)).toString("base64");
  return `url("data:font/woff2;base64,${b64}")`;
});

Fail the build if the inlined CSS blows past budget. Cheap insurance against accidentally inlining a full family.

import { statSync } from "node:fs";

const BUDGET = 200 * 1024; // 200 KB
const size = statSync("dist/styles.css").size;
if (size > BUDGET) {
  console.error(`CSS ${(size/1024).toFixed(0)}KB > budget 200KB`);
  process.exit(1);
}

When you'd rather shell out than write Node. The -A / -w 0 flags are mandatory — without them the 76-column wrap breaks lightningcss.

# openssl: -A = no line wrapping
openssl base64 -A -in Brand.woff2 -out Brand.b64

# GNU coreutils: -w 0 = no line wrapping
base64 -w 0 Brand.woff2 > Brand.b64

# build the data URI prefix
printf 'url("data:font/woff2;base64,%s") format("woff2")' "$(cat Brand.b64)"

If your encoder wraps at 76 columns (RFC 2045 MIME default — openssl base64 and base64 without flags both do), lightningcss strips the whole @font-face and leaves only font-family. No warning; the font vanishes after a Next.js or Tailwind v4 build. Always emit single-line: toString('base64'), openssl base64 -A, or base64 -w 0.

If your encoder emits URL-safe base64 (- and _ instead of + and /), lightningcss passes it through unchanged, but the browser's atob throws Invalid character and the font fails. The data: scheme requires the standard alphabet (RFC 4648 §4). Never pass a --url-safe/urlsafe flag for font CSS — toString('base64') and b64encode already use the standard alphabet.

An empty MIME defaults to text/plain; the browser downloads the data URI but refuses to interpret the bytes as a font, with no console error. Always emit a real font/* type. Build the MIME from the font's actual format, not the file extension — a .ttf that's really OpenType should be font/otf.

Encoding the font per-request (in an Express handler, a serverless function, a render loop) recomputes a byte-identical string every time and adds latency. Base64-encode once at build time and serve the cached artefact. The only legitimate runtime case is a genuinely user-supplied font, which is rare.

A full multi-weight family inlined into one render-blocking CSS file can balloon it to hundreds of KB. Add a CI size gate and prefer selective inlining (critical weight only). For the web, an external preloaded WOFF2 is almost always faster — see base64 vs external files.

Base64'd TTF can gzip ~17% larger than gzipping the raw TTF, because TTF has compressible structure that base64 scrambles; WOFF2 base64 stays within ~1% because WOFF2 is pre-compressed. Convert TTF to WOFF2 before inlining with ttf-to-woff2, then encode the WOFF2.

If your app sends a Content-Security-Policy with font-src (or only default-src), the inlined font is blocked unless data: is listed. The CSS parses; the font silently falls back. Add font-src 'self' data: — and remember to update any per-environment CSP your CI deploys.

Embedding inlined fonts in a CSS source map can push it past the ~10 MB limit devtools will load, silently breaking your maps. Strip data URIs from source-map inputs (postcss-discard-sourcemap-data or equivalent) or build the font CSS as a separate, source-map-disabled file.

A replace pattern matching only url("...") skips url('...') and unquoted url(...). If your source CSS mixes quoting styles, broaden the pattern or normalise the CSS first, or some fonts stay external silently. JAD's encoder always emits the double-quoted form, so standardising on it simplifies the regex.

Variable fonts bundle many weights into one file to be fetched once and cached. Inlining a 100-200 KB variable font pays the +33% penalty on a large, render-blocking, non-cacheable payload. Keep variable fonts external and preloaded; inline only static subsets generated with font-subsetter.