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

github ↗package ↗homepage ↗

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.

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).

import { build } from 'zig-build'

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 footguns

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.

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.

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.

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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

9 hits · last 30 days

gptbot

ahrefsbot

script

Resources

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

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

homepagehttps://zig-build.com ↗