node-fontnik

If prebuilt binaries are unavailable, you must build the module from source. This requires installing system dependencies first, then running the rebuild command.

1. Install system dependencies

macOS

brew install cmake ninja boost zlib

Linux (Debian/Ubuntu)

sudo apt-get install cmake ninja-build zlib1g-dev libboost-dev

2. Run the build

Execute the following command to compile the native module:

npm run rebuild

Note: N-API headers (node-addon-api, node-api-headers), protozero, and FreeType are automatically fetched by CMake during the configuration step.

Releases are published exclusively via CI using npm OIDC trusted publishing. There is no local publishing path. An accidental local npm publish will fail because the prepublishOnly script runs check-binaries, which requires all three platform prebuilds to be present.

Release Steps:

1. Bump the version in package.json and update CHANGELOG.md.
2. Open a PR, get it reviewed, and merge to main.
3. In GitHub, navigate to Actions → NPM release → Run workflow.
4. Approve the npm-release environment gate when prompted.

The workflow builds/tests on darwin-arm64, linux-x64, and linux-arm64, verifies the tarball, publishes to npm, and creates a GitHub release.

You can install node-fontnik using npm. Prebuilt binaries are provided for the following platforms:

• macOS arm64 (darwin-arm64)
• macOS x64 (darwin-x64)
• Linux x64 (linux-x64)
• Linux arm64 (linux-arm64)

Requirements:

• Node.js 20 or later is required.

If a matching prebuilt binary is not available for your platform, npm install will attempt to compile the module from source using CMake.

To mirror the CI environment (Ubuntu 22.04) on a Mac or any host with Docker, you can use the provided scripts to build and test Linux binaries.

Build and test all architectures (Release)

./scripts/docker-linux-test.sh

Build and test a specific architecture and build type

./scripts/docker-linux-test.sh x64 Debug

Release builds will write the output to prebuilds/linux-<arch>/fontnik.node.

To develop locally, you must install system dependencies and rebuild the native bindings. On macOS, use Homebrew to install cmake, ninja, boost, and zlib.

Note that npm install will attempt to skip compilation if a matching prebuild exists in prebuilds/. If no prebuild is found, scripts/install-native.js will trigger a rebuild unless the CI=true environment variable is set.

# macOS setup
brew install cmake ninja boost zlib

# Install dependencies and rebuild
npm ci --ignore-scripts
npm run rebuild
npm test

Use composite() to merge multiple glyph (SDF) protocol buffers (PBFs) into a single re-encoded PBF. When combining buffers, the order of the array determines the glyph priority (later buffers can override earlier ones).

Parameters:

• buffers: An array of buffer objects representing individual glyph PBFs.
• callback: A function called with callback(err, res), where res is the combined protocol buffer result.

fontnik.composite([buffer1, buffer2], (err, res) => {
  if (err) throw err;
  // res is the composited protocol buffer
});

Use range() to extract a specific range of glyphs from a font file as a protocol buffer. This is useful for generating specific subsets of glyphs for map styling.

Parameters:

• options: An object containing:
  • font: The font file as a buffer.
  • start: The starting unicode point (number).
  • end: The ending unicode point (number).
• callback: A function called with callback(err, res), where res is the resulting protocol buffer.

fontnik.range({
  font: fontBuffer,
  start: 32,
  end: 126
}, (err, res) => {
  if (err) throw err;
  // res is the protocol buffer result
});

Use load() to inspect a font file and retrieve its metadata, such as the family name, style name, and supported unicode points.

Parameters:

• font: The font file as a buffer.
• callback: A function called with callback(err, res), where res is an array of font style metadata objects.

Metadata Object Shape: Each object in the returned array contains:

• family_name: The name of the font family (e.g., `

If you encounter an error stating fontnik native module not found for <platform>-<arch>, it means the compiled native binary (fontnik.node) could not be located in the prebuilds or build directories. This typically happens when the prebuilt binary for your specific platform and architecture is unavailable or when the module hasn't been compiled locally.

To resolve this, attempt to rebuild the native module using the following command:

npm run rebuild

The build-glyphs CLI tool automates the process of converting a font stack into Mapbox glyph PBF files. It processes the font stack in chunks of 256 characters (covering the Unicode range up to 65535) and writes each chunk as a .pbf file to the specified output directory. The tool uses a worker queue based on the number of available CPU cores to parallelize the generation process.

Usage:

build-glyphs <fontstack path> <output dir>

Arguments:

• <fontstack path>: The path to the file containing the font stack.
• <output dir>: The directory where the generated .pbf files will be saved. This directory must already exist.

build-glyphs ./fonts/open-sans/OpenSans-Regular.ttf ./glyphs