{"id":14396,"library":"zig-build","title":"Node.js Native Addon Builder with Zig","description":"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.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/solarwindscloud/zig-build","tags":["javascript","native","addon","bindings","napi","node-api","c","c++","zig","typescript"],"install":[{"cmd":"npm install zig-build","lang":"bash","label":"npm"},{"cmd":"yarn add zig-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add zig-build","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Node-API (N-API) development. zig-build will automatically detect and include its headers if present.","package":"node-addon-api","optional":true}],"imports":[{"note":"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).","wrong":"const { build } = require('zig-build')","symbol":"build","correct":"import { build } from 'zig-build'"}],"quickstart":{"code":"import { build } from 'zig-build';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\n// Common configuration for all targets\nconst commonConfig = {\n  sources: [\n    path.join(__dirname, 'src', 'addon.cc'),\n    path.join(__dirname, 'src', 'util.cc')\n  ],\n  std: 'c++17' // Specify C++ standard\n};\n\n(async () => {\n  try {\n    await build({\n      windows: {\n        target: 'x86_64-windows',\n        output: path.join(__dirname, 'dist', 'windows', 'addon.node'),\n        ...commonConfig\n      },\n      'linux-x64': {\n        target: 'x86_64-linux-gnu',\n        output: path.join(__dirname, 'dist', 'linux-x64', 'addon.node'),\n        ...commonConfig\n      },\n      'linux-arm64': {\n        target: 'aarch64-linux-gnu',\n        output: path.join(__dirname, 'dist', 'linux-arm64', 'addon.node'),\n        ...commonConfig\n      }\n    });\n    console.log('Native addons built successfully for all specified targets!');\n  } catch (error) {\n    console.error('Error during build:', error);\n    process.exit(1);\n  }\n})();","lang":"typescript","description":"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."},"warnings":[{"fix":"Rewrite legacy NAN addons to use the Node-API (N-API) specification, leveraging `node-addon-api` for C++ abstractions.","message":"`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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Unlike 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.3.0':13 'addon':3,27,93,98,104,167 'api':35,38,92,172 'approach':70 'automat':78 'bind':168 'build':9,20,79,134,144 'builder':4 'c':173,174 'cach':80 'cadenc':151 'characterist':155 'clang':61 'class':74 'cmake':51 'cmake-j':50 'combin':118 'compil':24,58,68,77 'configur':147 'cpu':121 'cross':23,76 'cross-compil':22,75 'current':10,153 'depend':131 'deprec':95 'design':18 'differenti':40 'direct':54 'download':105 'earli':163 'elimin':63 'enabl':71 'evolv':159 'exclus':88 'experi':127 'first':73 'first-class':72 'flexibl':148 'focus':31 'function':135 'gyp':48 'handl':102 'improv':125 'instal':107 'instead':109 'intent':94 'irregular':154 'javascript':141,165 'js':52 'legaci':96 'leverag':55 'libc':85 'librari':17,87,138 'like':45 'link':83 'modern':16 'n':37,91 'n-api':36,90 'nan':97 'napi':169 'nativ':2,26,103,166 'need':65 'node':34,47,171 'node-api':33,170 'node-gyp':46 'node.js':1,25 'npm':115 'optionaldepend':117 'os':120 'packag':123 'project':160 'promot':111 'provid':146 'rapid':158 'reduc':129 'releas':150 'runtim':130 'script':145 'specif':122 'stage':164 'static':82 'strong':30 'support':89 'system':67 'time':108 'tool':44 'tradit':43 'typescript':143,176 'use':113 'user':126 'version':12 'within':139 'wrapper':62 'zig':6,8,57,133,175 'zig-build':7,132","created_at":"2026-04-20T01:59:29.174428+00:00","updated_at":"2026-04-20T01:59:29.174428+00:00","problems":[{"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.","cause":"A generic compilation error indicating issues with source files, compiler flags, missing dependencies, or an invalid target specification.","error":"Error: Command failed: zig build -target ..."},{"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.","cause":"Attempting to use the `build` function without properly importing it in an ESM context, or trying to use `require()` with this ESM-first library.","error":"ReferenceError: build is not defined"},{"fix":"Install `node-addon-api` as a development dependency: `npm install --save-dev node-addon-api` or `yarn add --dev node-addon-api`.","cause":"The `node-addon-api` package, which provides necessary C++ headers for N-API development, has not been installed as a dependency.","error":"Error: 'node-addon-api' header not found in include path"},{"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`).","cause":"The `target` string provided in the build configuration is not a valid or recognized Zig compilation target.","error":"Error: Invalid target triple: 'my-custom-target'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://zig-build.com","github":"https://github.com/solarwindscloud/zig-build","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/zig-build","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}