zig-build

library0.3.0jsnpmunverified

zig-build, currently at version 0.3.0, is a modern library designed for building and cross-compiling Node.js native addons, with a strong focus on Node-API (N-API). It differentiates itself from traditional tools like node-gyp and cmake-js by directly leveraging the Zig compiler and its Clang wrapper, eliminating the need for system compilers. This approach enables first-class cross-compilation, automatic build caching, and static linking of libc++. The library exclusively supports N-API addons, intentionally deprecating legacy NAN addons, and does not handle native addon downloading at install time. Instead, it promotes the use of npm's `optionalDependencies` combined with `os`/`cpu` specific packages for improved user experience and reduced runtime dependencies. `zig-build` functions as a library within a JavaScript or TypeScript build script, providing configuration flexibility. The release cadence is currently irregular, characteristic of a rapidly evolving project in its early stages.

devops

npm install zig-build

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ZIG-BUILD

zig-build

devopsjavascriptv0.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

build

✓ import { build } from 'zig-build'

✗ const { build } = require('zig-build')

zig-build is designed as an ESM-first library; use `import` in a module context (e.g., .mjs file or `"type": "module"` in package.json).

Demonstrates how to configure and build a native Node.js addon for multiple operating system and architecture targets (Windows x64, Linux x64, Linux ARM64) within a single `build` script call.

import { build } from 'zig-build'; import path from 'path'; import { fileURLToPath } from 'url'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); // Common configuration for all targets const commonConfig = { sources: [ path.join(__dirname, 'src', 'addon.cc'), path.join(__dirname, 'src', 'util.cc') ], std: 'c++17' // Specify C++ standard }; (async () => { try { await build({ windows: { target: 'x86_64-windows', output: path.join(__dirname, 'dist', 'windows', 'addon.node'), ...commonConfig }, 'linux-x64': { target: 'x86_64-linux-gnu', output: path.join(__dirname, 'dist', 'linux-x64', 'addon.node'), ...commonConfig }, 'linux-arm64': { target: 'aarch64-linux-gnu', output: path.join(__dirname, 'dist', 'linux-arm64', 'addon.node'), ...commonConfig } }); console.log('Native addons built successfully for all specified targets!'); } catch (error) { console.error('Error during build:', error); process.exit(1); } })();

Debug

Known issues

breaking`zig-build` exclusively supports Node-API (N-API) addons and explicitly does not provide support for legacy Node Addon API (NAN) addons. Projects relying on NAN will need to migrate to N-API.

fix

Rewrite legacy NAN addons to use the Node-API (N-API) specification, leveraging `node-addon-api` for C++ abstractions.

affects: >=0.1.0

gotcha`zig-build` does not provide mechanisms for downloading native addons at install time. It recommends using npm's `optionalDependencies` combined with `os` and `cpu` specific npm packages for distributing prebuilt binaries.

fix

Structure your project to use separate `optionalDependencies` entries in `package.json` for different target platforms, each containing the appropriate prebuilt native addon. Do not expect `zig-build` to handle runtime compilation on end-user machines.

affects: >=0.1.0

gotchaUnlike tools like `node-gyp`, `zig-build` is not a CLI tool and must be imported and used programmatically within a build script (JavaScript or TypeScript). It does not infer the compilation target from the current machine; targets must be explicitly specified.

fix

Create a dedicated build script (e.g., `build.mjs` or `build.ts`) and import the `build` function. Always explicitly define the `target` property within your build configuration objects for each desired platform.

affects: >=0.1.0

gotchaThe `node-addon-api` package, while often used with N-API, is a peer dependency and must be installed separately in your project's `devDependencies` if you intend to use its C++ abstractions.

fix

Ensure `node-addon-api` is installed in your project by running `npm install --save-dev node-addon-api` or `yarn add --dev node-addon-api`.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Command failed: zig build -target ...

A generic compilation error indicating issues with source files, compiler flags, missing dependencies, or an invalid target specification.

fix

Carefully review the console output for specific Zig compiler errors. Check your `sources` paths, `std` version, `defines`, `libraries`, and `target` options in your build configuration object. Ensure all source files exist and are correctly referenced.

ReferenceError: build is not defined

Attempting to use the `build` function without properly importing it in an ESM context, or trying to use `require()` with this ESM-first library.

fix

Ensure your build script is an ESM module (e.g., has a `.mjs` extension or `"type": "module"` in `package.json`) and use `import { build } from 'zig-build'`. If using CommonJS, dynamic `import()` might be an option, but native ESM is recommended.

Error: 'node-addon-api' header not found in include path

The `node-addon-api` package, which provides necessary C++ headers for N-API development, has not been installed as a dependency.

fix

Install `node-addon-api` as a development dependency: `npm install --save-dev node-addon-api` or `yarn add --dev node-addon-api`.

Error: Invalid target triple: 'my-custom-target'

The `target` string provided in the build configuration is not a valid or recognized Zig compilation target.

fix

Consult the official Zig documentation or run `zig targets` in your terminal to see a list of supported target triples. Ensure your target string follows the correct format (e.g., `x86_64-linux-gnu`).

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

node-addon-apioptionalRequired for Node-API (N-API) development. zig-build will automatically detect and include its headers if present.

Agent activity

26 hits · last 30 days

node

Resources

githubhttps://github.com/solarwindscloud/zig-build ↗

packagehttps://www.npmjs.com/package/zig-build ↗

homepagehttps://zig-build.com ↗