rollup-plugin-font-subsetter

0.2.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that subsets webfonts at build time based on the characters used in static source files (HTML, CSS, JavaScript/TypeScript) in the bundle. Current stable version: 0.2.0. Release cadence: low, experimental. Key differentiators: automatically extracts character set from bundled assets, uses subset-font under the hood, ships TypeScript types, supports only .woff2 format. Compared to alternatives like 'font-spider' or manual subsetting, it integrates directly into the Rollup build pipeline and requires no runtime overhead. Limitations: does not handle dynamic content or obfuscated code; character set extraction may be incomplete.

Common errors

error Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /path/to/rollup-plugin-font-subsetter/index.js ↓

cause The package is ESM-only and cannot be required with require().

fix

Use import syntax or set 'type': 'module' in package.json.

error TypeError: fontSubsetter is not a function ↓

cause Improper import or no default export; referencing a non-existent export.

fix

Use named import: import { fontSubsetter } from 'rollup-plugin-font-subsetter'

error rollup-plugin-font-subsetter: No font files found to subset ↓

cause No .woff2 files were detected in the bundle output.

fix

Ensure that you have .woff2 font files referenced in your source code (e.g., via CSS @font-face) and that the plugin runs after CSS processing.

Warnings

gotcha Does not subset fonts used in dynamic content (e.g., JavaScript string interpolation). Only static files in the bundle are analyzed. ↓

fix Ensure all possible characters are present in source files or manually specify a character set using plugin options.

gotcha Only supports .woff2 font files. Other formats such as .woff, .ttf, .otf are ignored. ↓

fix Convert fonts to .woff2 format before using this plugin, or use other tools for non-woff2 fonts.

gotcha Character set extraction may be incomplete for obfuscated or minified code (e.g., property names mangled). ↓

fix Ensure source code is not obfuscated before build, or manually specify additional characters.

deprecated This package has low release cadence and may not be actively maintained. ↓

fix Check for newer versions or alternative plugins if issues arise.

Install

npm install rollup-plugin-font-subsetter

yarn add rollup-plugin-font-subsetter

pnpm add rollup-plugin-font-subsetter

Imports

fontSubsetter

wrong

const fontSubsetter = require('rollup-plugin-font-subsetter')

correct

import { fontSubsetter } from 'rollup-plugin-font-subsetter'

ESM-only package; does not support CommonJS require().

FontSubsetterOptions

wrong

import { FontSubsetterOptions } from 'rollup-plugin-font-subsetter' (wrong, it's a type)

correct

import type { FontSubsetterOptions } from 'rollup-plugin-font-subsetter'

TypeScript type export only; use type import for runtime-free code.

default import

wrong

import fontSubsetter from 'rollup-plugin-font-subsetter' (no default export)

correct

import { fontSubsetter } from 'rollup-plugin-font-subsetter'

Only named export is available; no default export.

Quickstart

Minimal Rollup configuration using the fontSubsetter plugin with TypeScript.

import { defineConfig } from 'rollup';
import { fontSubsetter } from 'rollup-plugin-font-subsetter';
export default defineConfig({
  input: 'src/index.js',
  output: { dir: 'dist', format: 'es' },
  plugins: [
    fontSubsetter({
      // Optional options
    })
  ]
});