Skip to content
@staticbolt/core

Convert Fonts CLI Plugin

A staticbolt CLI plugin that registers a convert-fonts command for converting TTF font files to WOFF2 format. WOFF2 is a compressed font format with smaller files and better performance than TTF.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { convertFontsCliPlugin } from "@staticbolt/core/plugins";


export default defineConfig({
  plugins: [convertFontsCliPlugin()],
});

Then run from the command line:

Terminal window
npx staticbolt convert-fonts --fonts "src/**/*.ttf" --out-dir "./dist/fonts"
# or using the alias
npx staticbolt woff2 --fonts "src/**/*.ttf" --out-dir "./dist/fonts"

Plugin Options

command

  • Type: string
  • Default: "convert-fonts"

The name of the CLI command to register.

convertFontsCliPlugin({
  command: "fonts",
});

aliases

  • Type: string[]
  • Default: ["woff2"]

Other names that also run the convert-fonts command.

convertFontsCliPlugin({
  aliases: ["woff2", "fonts"],
});

fonts

  • Type: string
  • Default: undefined (required at runtime)

Default glob pattern for matching TTF font files. If provided, this sets the default value for the --fonts command-line option.

convertFontsCliPlugin({
  fonts: "src/**/*.ttf",
});

exclude

  • Type: string
  • Default: undefined (optional)

Default glob pattern for excluding files from conversion. If provided, this sets the default value for the --exclude command-line option.

convertFontsCliPlugin({
  exclude: "**/node_modules/**",
});

outDir

  • Type: string
  • Default: undefined (required at runtime)

Default output directory for converted WOFF2 files. If provided, this sets the default value for the --out-dir option.

convertFontsCliPlugin({
  outDir: "./dist/fonts",
});

Command Line Options

--fonts <pattern>

Required. A glob pattern to match TTF font files to convert.

Terminal window
npx staticbolt convert-fonts --fonts "fonts/**/*.ttf"

--exclude <pattern>

Optional. A glob pattern to exclude input files from conversion.

Terminal window
npx staticbolt convert-fonts --fonts "src/**/*.ttf" --exclude "src/deprecated/**"

--out-dir <path> / -o <path>

Required. The output directory for the converted WOFF2 files.

Terminal window
npx staticbolt convert-fonts --fonts "src/**/*.ttf" --out-dir "./dist/fonts"
npx staticbolt convert-fonts --fonts "src/**/*.ttf" -o "./dist/fonts"

Behavior

When executed, the convert-fonts command:

  1. Matches font files using the provided --fonts glob pattern
  2. Excludes files matching the --exclude pattern (if provided)
  3. For each matched TTF file:
    • Converts it to WOFF2 format using the ttf2woff2 library
    • Preserves the original filename with .woff2 extension
    • Saves the output to the specified --out-dir
  4. Creates the output directory if it does not exist

This plugin usually goes last in the plugins array, next to the other CLI plugins. It does not take part in the build pipeline itself.