A WebAssembly (WASM) version of msdf-atlas-gen. It runs the original C++ generator compiled to WASM through a Node.js CLI.

Quick start

With Node.js 8.0.0 or later and npm installed:

npx @uno.build/fonts font.ttf

This generates font.png and font.json using the default mtsdfx atlas type.

See the Fonts documentation for the usage guide, CLI options, and MTSDFX reference.

Third-party licenses

This software is based in part on the work of the FreeType Team. Portions of this software are copyright © 2024 The FreeType Project (https://www.freetype.org). All rights reserved.

See Third-party notices for the components included in the WebAssembly build and their license texts, distributed with this package.

Development

The CLI uses CommonJS and requires Node.js 8.0.0 or later. Development and publishing use Vite and Playwright, which require Node.js ^20.19.0 || >=22.12.0 with the current dependencies. The build produces a browser ES module and a separate Node-compatible WASM loader in dist/node/. To run the CLI tests against an older Node binary, use MSDF_CLI_NODE=/path/to/node npm run test:cli from the development environment.

To build from source, clone the original msdf-atlas-gen repository into this project's root and check out the pinned revision:

git clone https://github.com/Chlumsky/msdf-atlas-gen.git msdf-atlas-gen
git -C msdf-atlas-gen checkout --detach 6148900d59423059bafde2f51a0cb303184404bd
git -C msdf-atlas-gen submodule update --init msdfgen
npm install
npm run build:wasm

The submodule command checks out the matching msdfgen revision. The build scripts download the other pinned dependencies, including Artery Font and Skia. The official checkout is ignored by Git in this project and remains unchanged during builds: the scripts apply wasm/upstream.patch to a staged copy instead. Build prerequisites include Node.js/npm, Git, a C/C++ toolchain, CMake, Ninja, Python 3, Make, and the shell utilities used by the scripts. The scripts install the pinned Emscripten SDK. Dependency versions and revisions are defined in scripts/versions.sh.

Command	Description
npm run build:reference	Builds the official C++ CLI with pinned versions to use as the test reference.
npm run build:wasm	Builds the dependencies and generates the JavaScript loader and WASM module used by the CLI.
npm run test:reference	Runs the reference CLI and compares its results with the saved corpus.
npm run test:wasm	Inspects the WASM exports and verifies that it has no pthread imports or imported memory.
npm run test:node	Smoke-tests WASM initialization, filesystem access, variable axes, and exporter file creation. Does not validate the full contents of every format.
npm run test:cli	Checks the Node CLI against the C++ reference, host filesystem access, Unicode JSON, and the mtsdfx conversion and validation.
npm run reference:update	Regenerates the expected corpus using the reference CLI. Modifies corpus files; run only when intentionally updating the reference results.

The test commands use existing build artifacts. To rebuild both engines and run the existing reference, WASM, Node, and CLI checks (partial coverage):

npm run build:reference
npm run build:wasm
npm run test:reference
npm run test:wasm
npm run test:node
npm run test:cli

Build and test paths can be configured with environment variables. Defaults below are relative to the project root unless shown as absolute paths.

Variable	Default	Purpose
MSDF_ATLAS_UPSTREAM_DIR	msdf-atlas-gen	Checkout of the pinned upstream source.
MSDF_ATLAS_DEPS_DIR	.wasm-deps	Downloaded dependencies, SDK, and dependency build artifacts.
MSDF_ATLAS_ARTERY_FONT_DIR	$MSDF_ATLAS_DEPS_DIR/artery-font-format	Artery Font source used while staging upstream. Must match the pinned revision.
MSDF_ATLAS_STAGE_DIR	.build-src/msdf-atlas-gen	Disposable patched source copy, recreated by the build scripts.
MSDF_ATLAS_WASM_BUILD_DIR	build-wasm-root	CMake build directory for the WASM module.
MSDF_NATIVE_CLI	.wasm-deps/native-reference/bin/msdf-atlas-gen	Reference executable used by tests. Set this too if the native build uses a custom dependency directory.

Use absolute paths for build-directory overrides.

Test package

npm run build:wasm
npm pack
npx file:./uno.build-fonts-0.1.0.tgz tests/assets/complex.ttf

Publishing to npm

npm publish

npm publish automatically runs prepublishOnly, which builds WASM and the API once, then runs the full test suite. Publication proceeds only if both succeed; no separate build, test, or prepublishOnly command is needed.