zapi

A Zig N-API wrapper library and CLI for building and publishing cross-platform Node.js native addons.

Overview

zapi provides two main components:

1. Zig Library (src/) - Idiomatic Zig bindings for the Node.js N-API, making it easy to write native addons in Zig
2. CLI Tool (ts/) - Build tooling for cross-compiling and publishing multi-platform npm packages

Installation

npm install -D @chainsafe/zapi

Add the Zig dependency to your build.zig.zon:

.dependencies = .{
    .zapi = .{
        .url = "https://github.com/chainsafe/zapi/archive/<commit>.tar.gz",
        .hash = "...",
    },
},

---

Zig Library

Quick Start

const napi = @import("napi");

comptime {
    napi.module.register(initModule);
}

fn initModule(env: napi.Env, module: napi.Value) !void {
    // Export a string
    try module.setNamedProperty("greeting", try env.createStringUtf8("Hello from Zig!"));
    
    // Export a function
    try module.setNamedProperty("add", try env.createFunction("add", 2, napi.createCallback(2, add, .{}), null));
}

fn add(a: i32, b: i32) i32 {
    return a + b;
}

Core Types

Type	Description
Env	The N-API environment, provides methods to create values, throw errors, manage scopes
Value	A JavaScript value handle with methods for type checking, property access, conversions
CallbackInfo	Provides access to function arguments and this binding
HandleScope	Prevents garbage collection of values within a scope
EscapableHandleScope	Like HandleScope but allows one value to escape
Ref	A persistent reference to a value that survives garbage collection
Deferred	Resolver/rejecter for promises
AsyncWork	Run work on a thread pool with completion callback on main thread
ThreadSafeFunction	Call JavaScript from any thread safely
AsyncContext	Context for async resource tracking

Creating Functions

Manual Style

Full control using raw Env and Value:

fn add_manual(env: napi.Env, info: napi.CallbackInfo(2)) !napi.Value {
    const a = try info.arg(0).getValueInt32();
    const b = try info.arg(1).getValueInt32();
    return try env.createInt32(a + b);
}

Automatic Conversion with createCallback

Let zapi handle argument/return conversion:

// Arguments and return value are automatically converted
fn add(a: i32, b: i32) i32 {
    return a + b;
}

// Register with automatic wrapping
try env.createFunction("add", 2, napi.createCallback(2, add, .{}), null);

Argument Hints

Control how arguments are converted:

napi.createCallback(2, myFunc, .{
    .args = .{ .env, .auto, .value, .data, .string, .buffer },
    .returns = .value,  // or .string, .buffer, .auto
});

Hint	Description
.auto	Automatic type conversion
.env	Inject napi.Env
.value	Pass raw napi.Value
.data	User data pointer passed to createFunction
.string	Convert to/from []const u8
.buffer	Convert to/from byte slice

Creating Classes

const Timer = struct {
    start: i64,
    
    pub fn read(self: *Timer) i64 {
        return std.time.milliTimestamp() - self.start;
    }
};

try env.defineClass(
    "Timer",
    0,
    timerConstructor,
    null,
    &[_]napi.c.napi_property_descriptor{
        .{ .utf8name = "read", .method = napi.wrapCallback(0, Timer.read) },
    },
);

Async Work (Thread Pool)

Run CPU-intensive work off the main thread:

const Work = struct {
    a: i32,
    b: i32,
    result: i32,
    deferred: napi.Deferred,
};

fn execute(env: napi.Env, data: *Work) void {
    // Runs on thread pool - don't call JS here!
    data.result = data.a + data.b;
}

fn complete(env: napi.Env, status: napi.status.Status, data: *Work) void {
    // Back on main thread - resolve the promise
    const result = env.createInt32(data.result) catch return;
    data.deferred.resolve(result) catch return;
}

// Create async work
const work = try napi.AsyncWork(Work).create(env, null, name, execute, complete, &data);
try work.queue();

Thread-Safe Functions

Call JavaScript from any thread:

const tsfn = try env.createThreadsafeFunction(
    jsCallback,        // JS function to call
    context,           // User context
    "name",
    0,                 // Max queue size (0 = unlimited)
    1,                 // Initial thread count
    null,              // Finalize data
    null,              // Finalize callback
    myCallJsCallback,  // Called on main thread
);

// From any thread:
try tsfn.call(&data, .blocking);

Error Handling

All N-API calls return NapiError on failure:

fn myFunction(env: napi.Env) !void {
    // Errors propagate naturally
    const value = try env.createStringUtf8("hello");
    
    // Throw JavaScript errors
    try env.throwError("ERR_CODE", "Something went wrong");
    try env.throwTypeError("ERR_TYPE", "Expected a number");
}

---

CLI Tool

Configuration

Add a zapi field to your package.json:

{
  "name": "my-addon",
  "zapi": {
    "binaryName": "my-addon",
    "step": "my-lib",
    "targets": [
      "x86_64-unknown-linux-gnu",
      "x86_64-unknown-linux-musl",
      "aarch64-unknown-linux-gnu",
      "x86_64-apple-darwin",
      "aarch64-apple-darwin",
      "x86_64-pc-windows-msvc"
    ]
  }
}

Supported Targets

Target	Platform	Arch	ABI
aarch64-apple-darwin	macOS	arm64	-
x86_64-apple-darwin	macOS	x64	-
aarch64-unknown-linux-gnu	Linux	arm64	glibc
x86_64-unknown-linux-gnu	Linux	x64	glibc
x86_64-unknown-linux-musl	Linux	x64	musl
x86_64-pc-windows-msvc	Windows	x64	msvc

Global Options

Option	Description
--help, -h	Show help message
--version, -v	Show version number

Commands

zapi build

Build for a single target platform.

zapi build [options]

Option	Description	Default
--step	Zig build step	zapi.step from package.json
--target	Target triple	Current platform
--optimize	Debug, ReleaseSafe, ReleaseFast, ReleaseSmall	-
--zig-cwd	Working directory for zig build	.

zapi build-artifacts

Build for all configured targets and collect artifacts.

zapi build-artifacts [options]

Option	Description	Default
--step	Zig build step	zapi.step from package.json
--optimize	Optimization level	-
--zig-cwd	Working directory for zig build	.
--artifacts-dir	Output directory for artifacts	artifacts

Example output:

▶ Building my-addon for 6 target(s)...
[1/6] Building for x86_64-unknown-linux-gnu...
  → Moving artifact to artifacts/x86_64-unknown-linux-gnu
[2/6] Building for aarch64-apple-darwin...
  → Moving artifact to artifacts/aarch64-apple-darwin
...
✓ Built 6 artifact(s) to artifacts/

zapi prepublish

Prepare npm packages for publishing:

• Creates npm/<target>/ directories for each target
• Moves compiled .node binaries from artifacts into target packages
• Generates package.json for each target package (with correct os, cpu, libc)
• Updates the main package.json with optionalDependencies

zapi prepublish [options]

Option	Description	Default
--artifacts-dir	Directory containing built artifacts	artifacts
--npm-dir	Directory for npm packages	npm

Example output:

▶ Preparing [email protected] for publishing...
▶ Moving artifacts to npm packages...
  → x86_64-unknown-linux-gnu → npm/x86_64-unknown-linux-gnu/my-addon.node
▶ Generating target package.json files...
  → Created npm/x86_64-unknown-linux-gnu/package.json
▶ Updating package.json with optionalDependencies...
✓ Prepared 6 target package(s) in npm/

zapi publish

Publish all target-specific packages and the main package to npm.

zapi publish [options] [-- <npm-args>]

Option	Description	Default
--npm-dir	Directory containing npm packages	npm
--dry-run	Preview what would be published without publishing	false

Any arguments after -- are passed directly to npm publish (e.g., --access public, --tag beta).

Example dry-run:

zapi publish --dry-run

▶ [DRY RUN] Would publish 6 target package(s) + main package
  → Extra npm args: (none)
[1/7] Would publish x86_64-unknown-linux-gnu
  → Directory: /path/to/npm/x86_64-unknown-linux-gnu
...
✓ [DRY RUN] 7 package(s) would be published

Release Workflow

# 1. Build for all targets
zapi build-artifacts --optimize ReleaseFast

# 2. Prepare npm packages
zapi prepublish

# 3. Preview what will be published
zapi publish --dry-run

# 4. Publish to npm
zapi publish -- --access public

Error Handling

Set DEBUG=1 for full stack traces on errors.

---

Runtime Loading

requireNapiLibrary(packageDir)

Load the native addon, automatically selecting the correct binary for the current platform:

import { requireNapiLibrary } from "@chainsafe/zapi";
import { fileURLToPath } from "node:url";
import { dirname } from "node:path";

const __dirname = dirname(fileURLToPath(import.meta.url));
const addon = requireNapiLibrary(__dirname);

Resolution order:

1. Local build: zig-out/lib/<binaryName>.node
2. Published package: <pkg-name>-<target>

---

Example

See the example/ directory for a comprehensive example including:

• String properties
• Functions with manual and automatic argument handling
• Classes with methods
• Async work with promises
• Thread-safe functions

# Build the example
zig build

# Test it
node example/test.js

License

MIT