Skip to content
@staticbolt/core

Generate Font Face CLI Plugin

A staticbolt CLI plugin that registers a fontface command for generating CSS @font-face rules from font files. It writes the CSS you need to declare custom fonts in your stylesheets.

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 { generateFontFacesCliPlugin } from "@staticbolt/core/plugins";


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

Then run from the command line:

Terminal window
npx staticbolt fontface --fonts "src/fonts/**/*.woff2" --css-out "./src/styles/fonts.css"
# or using the alias
npx staticbolt font --fonts "src/fonts/**/*.woff2" --css-out "./src/styles/fonts.css"

Plugin Options

command

  • Type: string
  • Default: "fontface"

The name of the CLI command to register.

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

aliases

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

Other names that also run the generate-font-face command.

generateFontFacesCliPlugin({
  aliases: ["font", "fonts"],
});

fonts

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

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

generateFontFacesCliPlugin({
  fonts: "src/fonts/**/*.woff2",
});

exclude

  • Type: string
  • Default: undefined (optional)

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

generateFontFacesCliPlugin({
  exclude: "src/fonts/deprecated/**",
});

cssOut

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

Default output file path for the generated CSS file. If provided, this sets the default value for the --css-out option.

generateFontFacesCliPlugin({
  cssOut: "./src/styles/fonts.css",
});

fontDisplay

  • Type: "auto" | "block" | "swap" | "fallback" | "optional"
  • Default: "swap"

Default value for the CSS font-display property. This controls how the font displays while loading.

generateFontFacesCliPlugin({
  fontDisplay: "fallback",
});

Command Line Options

--fonts <pattern>

Required. A glob pattern to match the font files to generate @font-face rules for.

Terminal window
npx staticbolt fontface --fonts "fonts/**/*.woff2"

--exclude <pattern>

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

Terminal window
npx staticbolt fontface --fonts "fonts/**/*.woff2" --exclude "fonts/deprecated/**"

--css-out <path> / -o <path>

Required. The file path to write the generated CSS @font-face rules to.

Terminal window
npx staticbolt fontface --fonts "fonts/**/*.woff2" --css-out "./dist/fonts.css"
npx staticbolt fontface --fonts "fonts/**/*.woff2" -o "./dist/fonts.css"

--font-display <value>

Optional. The CSS font-display property to use in generated @font-face rules. One of: auto, block, swap, fallback, optional.

Terminal window
npx staticbolt fontface --fonts "fonts/**/*.woff2" --css-out "./dist/fonts.css" --font-display "swap"

Font Display Values

  • auto: the browser default, usually much like block.
  • block: the font face is not used, and the browser waits up to 3 seconds for the download.
  • swap: the font face is swapped in after the download, with no waiting.
  • fallback: a very short invisible period (~100ms), then a swap if the font has not loaded.
  • optional: a very short invisible period (~100ms), then the fallback if the font has not loaded.

Most projects use swap or fallback to avoid invisible text (FOIT).

Behavior

When executed, the generate-font-face command:

  1. Matches font files using the provided --fonts glob pattern
  2. Excludes files matching the --exclude pattern (if provided)
  3. For each matched font file:
    • Generates a CSS @font-face rule with proper font declarations
    • Applies the specified --font-display property
  4. Combines all generated rules into a single CSS file
  5. Saves the output to the specified --css-out path

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.