NAPI-RS

https://napi.rs/docs
Admin
NAPI-RS is a framework for building high-performance Node.js native modules using Rust with a CLI...
Tokens:154,841
Snippets:1,163
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### lib.rs: install and use napi-async-runtime

Source: https://napi.rs/docs/concepts/async-runtime

Install the runtime in a #[module_init] function, resolving configuration before calling install. The example exports an async function that sleeps and adds two numbers.

```rust
#[napi_derive::module_init]
fn init() {
  // Resolve your own configuration (env vars, defaults) FIRST; the scheduler
  // never reads the environment itself.
  napi_async_runtime::install(napi_async_runtime::RuntimeOptions::default())
    .expect("failed to install the shared async runtime");
}

#[napi]
pub async fn sleep_then_add(a: u32, b: u32, sleep_ms: u32) -> u32 {
  napi_async_runtime::sleep_until(
    std::time::Instant::now() + std::time::Duration::from_millis(u64::from(sleep_ms)),
  )
  .await;
  a + b
}
```

--------------------------------

### Clone and build napi-rs examples locally

Source: https://napi.rs/docs/more/examples

Commands to clone the napi-rs repository, install dependencies, build the @napi-rs/* packages, build the @examples/* packages with the in-repo CLI, and run the ava tests in the examples/napi directory.

```sh
git clone https://github.com/napi-rs/napi-rs.git
cd napi-rs
yarn
yarn build      # build the @napi-rs/* packages (CLI, wasm-runtime, ...)
yarn build:test # build the @examples/* packages with the in-repo CLI

cd examples/napi
yarn test       # ava
```

--------------------------------

### Install prerequisites for NAPI-RS manual setup

Source: https://napi.rs/docs/introduction/manual-setup

Verify the Rust toolchain and Node.js version, then install the NAPI-RS CLI locally in the JavaScript package that owns the addon. Node.js 22.13+ (or 24+) is required for the current CLI. Keeping the CLI local ensures builds and CI use the recorded version; run it via a package script or npx napi.

```sh
rustc --version
node --version
npm install --save-dev @napi-rs/cli@^3
```

--------------------------------

### Example package.json with napi binaryName

Source: https://napi.rs/docs/cli/build

Example package.json for a package that uses @napi-rs/cli and configures binaryName as snappy. This is the input before applying --js-package-name.

```json
{
  "name": "snappy",
  "version": "7.0.0",
  "napi": {
    "binaryName": "snappy"
  }
}
```

--------------------------------

### Install @napi-rs/cli@latest

Source: https://napi.rs/docs/more/v2-v3-migration-guide

Install the latest version of the NAPI-RS CLI as a dev dependency.

```sh
npm install --save-dev @napi-rs/cli@latest

```

--------------------------------

### Install dependencies with Yarn

Source: https://napi.rs/docs/introduction/simple-package

Enter the project directory and install dependencies using Yarn. This is for the Yarn template.

```sh
cd cool
yarn install
```

--------------------------------

### binding.gyp example with multiple targets

Source: https://napi.rs/docs/deep-dive/native-module

Example binding.gyp configuration defining four native module targets (addon1 to addon4), each with source files addon.cc and myobject.cc. After compilation, the modules are placed in build/Release/addon*.node.

```text
{
  "targets": [{
    "target_name": "addon1",
    "sources": [ "1/addon.cc", "1/myobject.cc" ]
  }, {
    "target_name": "addon2",
    "sources": [ "2/addon.cc", "2/myobject.cc" ]
  }, {
    "target_name": "addon3",
    "sources": [ "3/addon.cc", "3/myobject.cc" ]
  }, {
    "target_name": "addon4",
    "sources": [ "4/addon.cc", "4/myobject.cc" ]
  }]
}
```

--------------------------------

### run_script example

Source: https://napi.rs/docs/concepts/env

Example of running a JavaScript expression and asserting the result.

```rust
let result: i32 = env.run_script("2 + 2")?;
assert_eq!(result, 4);
```

--------------------------------

### Complete native addon example using NAN_METHOD and NAN_MODULE_INIT

Source: https://napi.rs/docs/deep-dive/history

A full example of a native addon that defines an Echo function and initializes the module. It uses Nan::ThrowError, Nan::Undefined, and Nan::Set to expose the function to JavaScript.

```cpp
NAN_METHOD(Echo)
{
    if(info.Length() < 1)
    {
        Nan::ThrowError("Wrong number of arguments.");
        return info.GetReturnValue().Set(Nan::Undefined());
    }

    info.GetReturnValue().Set(info[0]);
}

NAN_MODULE_INIT(InitAll)
{
    Nan::Set(
        target,
        Nan::New<String>("echo").ToLocalChecked(),
        Nan::GetFunction(Nan::New<v8::FunctionTemplate>(Echo)).ToLocalChecked());
}
```

--------------------------------

### cli.build(options)

Source: https://napi.rs/docs/cli/programmatic-api

Starts a build process and returns an object containing a task promise and an abort function to cancel the build.

```APIDOC
## cli.build(options)

### Description
Starts a build process and returns an object containing a task promise and an abort function to cancel the build.

### Method
Not specified (programmatic API)

### Endpoint
Not applicable (programmatic API)

### Parameters
#### Options
- **options** (object) - Required - Build options (not detailed in source)

### Returns
- **task** (Promise) - A promise that resolves when the build completes.
- **abort** (function) - A function that cancels the build.

### Example
```ts
const { task, abort } = await cli.build(options)

// Handle SIGINT to abort cleanly
process.on('SIGINT', () => {
  abort()
  process.exit(1)
})

const outputs = await task
```
```

--------------------------------

### create_function_from_closure example lib.rs

Source: https://napi.rs/docs/concepts/env

Rust example showing how to use env.create_function_from_closure with a closure that captures a variable and reads the first argument from the JavaScript side.

```rust
use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub fn create_function(env: &Env) -> Result<Function<u32, u32>> {
  let var_moved_into_closure = 42; // this variable is moved into the closure
  env.create_function_from_closure("rustClosure", move |ctx| {
    // get the first argument from the JavaScript side
    let result = var_moved_into_closure + ctx.get::<u32>(0)?;
    Ok(result)
  })
}
```

--------------------------------

### create_function example lib.rs

Source: https://napi.rs/docs/concepts/env

Rust example showing how to use env.create_function with a C callback. The callback function is marked with #[napi(no_export)] to prevent export to JavaScript.

```rust
use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub fn create_function(env: &Env) -> Result<Function<u32, u32>> {
  env.create_function("customFunction", custom_function_c_callback)
}

#[napi(no_export)]
fn custom_function(input: u32) -> u32 {
  input * 2
}
```

--------------------------------

### Install, build, and test the generated project with yarn or pnpm

Source: https://napi.rs/docs/introduction/getting-started

Installs dependencies, builds the native addon, and runs tests inside the generated project. The build compiles one native target (your host unless --target is passed) and produces the .node addon, index.js loader, and index.d.ts declarations when type generation is enabled.

```sh
cd cool
yarn install
yarn build
yarn test
```

```sh
cd cool
pnpm install
pnpm build
pnpm test
```

--------------------------------

### Import ESM addon

Source: https://napi.rs/docs/more/integrations

Example of importing the ESM addon using import.

```js
import { add } from '@scope/addon'
```

--------------------------------

### parseTriple() example for platform-specific binding names

Source: https://napi.rs/docs/cli/programmatic-api

Demonstrates using parseTriple() to extract platform information from a target triple and construct a platform-specific binding filename.

```ts
const triple = parseTriple('x86_64-unknown-linux-gnu')
// Returns: { platform: 'linux', arch: 'x64', abi: 'gnu', platformArchABI: 'linux-x64-gnu', ... }

const bindingName = `mylib.${triple.platformArchABI}.node`
// Result: 'mylib.linux-x64-gnu.node'
```

--------------------------------

### Artifact file naming convention

Source: https://napi.rs/docs/cli/artifacts

Example file names that each build job should upload, using the configured binary name and target ABI suffix.

```text
cool.darwin-arm64.node
cool.linux-x64-gnu.node
cool.win32-x64-msvc.node
cool.wasm32-wasi.wasm
```

--------------------------------

### Accepted artifact directory layout

Source: https://napi.rs/docs/cli/artifacts

Example directory layout produced by `actions/download-artifact` that the CLI searches recursively.

```text
artifacts/
├── bindings-aarch64-apple-darwin/
│   └── cool.darwin-arm64.node
├── bindings-x86_64-unknown-linux-gnu/
│   └── cool.linux-x64-gnu.node
└── bindings-x86_64-pc-windows-msvc/
    └── cool.win32-x64-msvc.node
```

--------------------------------

### Directory layout after collection

Source: https://napi.rs/docs/cli/artifacts

Example directory layout after running `yarn napi artifacts`, showing files in the root package and under `npm/`.

```text
.
├── cool.darwin-arm64.node
├── cool.linux-x64-gnu.node
├── cool.win32-x64-msvc.node
└── npm/
    ├── darwin-arm64/cool.darwin-arm64.node
    ├── linux-x64-gnu/cool.linux-x64-gnu.node
    └── win32-x64-msvc/cool.win32-x64-msvc.node
```

--------------------------------

### napi build for x86_64-unknown-linux-musl with -x

Source: https://napi.rs/docs/cross-build

Replaces the old nodejs-rust:lts-alpine image. Requires installing zig first, then running this command on a plain ubuntu-latest runner.

```bash
napi build --release --target x86_64-unknown-linux-musl -x
```

--------------------------------

### Next.js route handler using addon

Source: https://napi.rs/docs/more/integrations

Example route handler that imports the addon and uses it in a GET request. The runtime is set to 'nodejs' to ensure the addon runs in the Node.js runtime.

```ts
export const runtime = 'nodejs'

import { add } from '@scope/addon'

export function GET() {
  return Response.json({ value: add(20, 22) })
}
```

--------------------------------

### Create build.rs for NAPI-RS

Source: https://napi.rs/docs/introduction/manual-setup

Build script that calls napi_build::setup() to configure the output for the host platform. Required for the NAPI-RS build process.

```rust
fn main() {
  napi_build::setup();
}
```

--------------------------------

### Create and push the repository

Source: https://napi.rs/docs/introduction/simple-package

Initialize a git repository, commit the initial package, and push to the remote origin.

```sh
git init
git add .
git commit -m "Create napi-rs package"
git branch -M main
git remote add origin git@github.com:your-name/cool.git
git push -u origin main
```

--------------------------------

### package.json optionalDependencies for platform packages

Source: https://napi.rs/docs/introduction/getting-started

Example package.json showing optional platform-specific dependencies for a napi-rs package. The root package depends on these optional packages so the package manager installs only the binary matching the current OS, CPU, and libc.

```json
{
  "optionalDependencies": {
    "@cool/core-darwin-x64": "1.0.0",
    "@cool/core-win32-x64-msvc": "1.0.0",
    "@cool/core-linux-arm64-gnu": "1.0.0"
  }
}
```

--------------------------------

### Bind function to object with This<&Width>

Source: https://napi.rs/docs/concepts/inject-this

In a free function, use `This<&Width>` to bind the function to a JavaScript object. The function accesses the `value` field of the `Width` instance and returns `value + 1`. The JavaScript example creates a `Width` with value 1 and calls `plusOne` with `call(width)` to get 2.

```rust
use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi(constructor)]
pub struct Width {
  pub value: i32,
}

#[napi]
pub fn plus_one(this: This<&Width>) -> i32 {
  this.object.value + 1
}
```

```javascript
import { Width, plusOne } from './index.js'

const width = new Width(1)
console.log(plusOne.call(width)) // 2
```

--------------------------------

### npm: Install with wasm32 CPU flag

Source: https://napi.rs/docs/concepts/webassembly

Use this command to install a package with the wasm32 CPU target. After installation, verify the package was installed correctly with npm ls.

```sh
npm install --cpu=wasm32

```

```sh
npm ls @scope/my-addon-wasm32-wasi

```

--------------------------------

### Create custom Tokio runtime with create_custom_tokio_runtime

Source: https://napi.rs/docs/concepts/module-init

Implements a custom Tokio runtime initialization using the module_init macro. The example creates a multi-thread runtime with all features enabled and a custom thread name, then passes it to create_custom_tokio_runtime. The multi-thread Tokio runtime is target-dependent; gate the runtime setup or choose a runtime configuration supported by the WebAssembly target, though the module_init macro itself supports WebAssembly builds.

```rust
use napi::bindgen_prelude::create_custom_tokio_runtime;

#[napi_derive::module_init]
fn init() {
  let runtime = napi::tokio::runtime::Builder::new_multi_thread()
    .enable_all()
    .thread_name("my-native-module")
    .build();
  match runtime {
    Ok(rt) => create_custom_tokio_runtime(rt),
    Err(err) => eprintln!("failed to create custom Tokio runtime: {err}"),
  }
}

```

--------------------------------

### package.json napi configuration example

Source: https://napi.rs/docs/cli/napi-config

Shows a minimal `napi` configuration in `package.json` with `binaryName` and `targets`. All fields are optional; a standalone config file takes precedence when both are present.

```json
{
  "name": "@scope/addon",
  "napi": {
    "binaryName": "addon",
    "targets": ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
  }
}
```

--------------------------------

### create_string example

Source: https://napi.rs/docs/concepts/env

Example usage of create_string to create a JavaScript string.

```rust
let js_string = env.create_string("Hello, World!")?;
```

--------------------------------

### Universalize with custom --output-dir

Source: https://napi.rs/docs/cli/universalize

Combine binaries from a custom output directory. Must match the --output-dir used with napi build.

```sh
napi universalize --output-dir ./binaries
```

--------------------------------

### Illustrative output: Ok and QueueFull statuses

Source: https://napi.rs/docs/concepts/threadsafe-function

Shows an example of the output from the Rust function when the queue is full. The exact sequence varies, but a capacity of one guarantees backpressure behavior.

```text
Ok
Ok
QueueFull
QueueFull
QueueFull
QueueFull
QueueFull
QueueFull
QueueFull
QueueFull
...
```

--------------------------------

### Set up wasi-sdk and build WASI target

Source: https://napi.rs/docs/concepts/webassembly

Set WASI_SDK_PATH to the extracted wasi-sdk root, verify the clang and wasm-ld binaries exist, then run napi build for the wasm32-wasip1-threads target. The CLI sets Cargo's WASI linker variables to $WASI_SDK_PATH/bin/wasm-ld and fills only unset C/C++ toolchain variables.

```sh
export WASI_SDK_PATH=/absolute/path/to/wasi-sdk
test -x "$WASI_SDK_PATH/bin/clang"
test -x "$WASI_SDK_PATH/bin/wasm-ld"
napi build --platform --release --target wasm32-wasip1-threads
```

--------------------------------

### Build both architectures then universalize

Source: https://napi.rs/docs/cli/universalize

Typical macOS CI workflow: build both architectures (x86_64 and aarch64) with --release, then combine into universal binary.

```sh
napi build --release --target x86_64-apple-darwin
napi build --release --target aarch64-apple-darwin
napi universalize
```

--------------------------------

### Example: Adding a Symbol - index.js

Source: https://napi.rs/docs/concepts/module-init

JavaScript consumer that requires the compiled native module and accesses the custom properties added by the Rust example. Logs the symbol and version to verify they are exported correctly.

```javascript
const native = require('./index.node')

console.log(native.MY_SYMBOL) // Symbol(MY_MODULE_SYMBOL)
console.log(native.VERSION) // "1.0.0"
```

--------------------------------

### Browser loader using @napi-rs/wasm-runtime (my-addon.wasi-browser.js)

Source: https://napi.rs/docs/concepts/webassembly

Shows the imports and setup for a generated browser loader when browser.fs is true. It imports WASI, instantiateNapiModuleSync, emnapi plugins, and memfs/Buffer, then creates a memfs-backed fs and a WASI instance with preopens. This is condensed from example.wasi-browser.js; regenerate with napi build instead of editing by hand.

```typescript
import {
  WASI,
  instantiateNapiModuleSync,
  emnapiAsyncWorkPlugin,
  emnapiTSFNPlugin,
} from '@napi-rs/wasm-runtime'
import { memfs, Buffer } from '@napi-rs/wasm-runtime/fs'

// the generated loader re-exports these when `browser.fs` is true
const { fs: __fs, vol: __volume } = memfs()

const __wasi = new WASI({
  version: 'preview1',
  fs: __fs,
  preopens: {
    '/': '/',
  },
})
```

--------------------------------

### CLI usage: napi create-npm-dirs [--options]

Source: https://napi.rs/docs/cli/create-npm-dirs

Shows the basic CLI syntax for the create-npm-dirs command. Use this to create npm package directories for different platforms.

```sh
# CLI
napi create-npm-dirs [--options]
```

--------------------------------

### Install custom Tokio runtime in module_init

Source: https://napi.rs/docs/more/async-concurrency

Creates a custom Tokio runtime with 4 worker threads and installs it during module initialization. The runtime is consumed once; after shutdown and restart, NAPI-RS falls back to its default runtime.

```rust
use napi::create_custom_tokio_runtime;

#[napi_derive::module_init]
fn init() {
  let runtime = tokio::runtime::Builder::new_multi_thread()
    .worker_threads(4)
    .enable_all()
    .build();
  match runtime {
    Ok(runtime) => create_custom_tokio_runtime(runtime),
    Err(err) => eprintln!("failed to create custom Tokio runtime: {err}"),
  }
}

```

--------------------------------

### Build the addon with pnpm

Source: https://napi.rs/docs/introduction/simple-package

Run the release build for your current platform using pnpm. The script invokes `napi build --platform --release` and produces files like `cool.darwin-arm64.node`, `index.js`, and `index.d.ts`.

```sh
pnpm build
```

--------------------------------

### AsyncRuntime trait definition

Source: https://napi.rs/docs/concepts/async-runtime

The unsafe trait that a backend must implement. It defines spawn, block_on, enter, start, shutdown, and spawn_blocking. Default implementations are provided for enter (no-op guard), start (no-op), and spawn_blocking (declines).

```rust
pub unsafe trait AsyncRuntime: Send + Sync + 'static {
  fn spawn(
    &self,
    task: AsyncRuntimeTask,
  ) -> std::result::Result<(), AsyncRuntimeRejection<AsyncRuntimeTask>>;

  fn block_on(&self, future: Pin<&mut dyn Future<Output = ()>>) -> Result<()>;

  fn enter(&self) -> Result<Box<dyn AsyncRuntimeGuard + '_>> { ... } // default: no-op guard

  fn start(&self) -> Result<()> { ... } // default: no-op

  fn shutdown(&self) -> Result<()>;

  fn spawn_blocking(
    &self,
    work: Box<dyn FnOnce() + Send + 'static>,
  ) -> std::result::Result<(), AsyncRuntimeRejection<Box<dyn FnOnce() + Send + 'static>>> { ... } // default: declines
}
```

--------------------------------

### Run deployment environment probes

Source: https://napi.rs/docs/more/integrations

Run these probes inside the final container/archive environment to check the Node.js executable path, platform/architecture, glibc version, and installed addon package. If the addon works before bundling but not from the final bundle, inspect whether the bundler relocated the loader, renamed the .node file, removed an optional dependency, or selected an Edge/browser runtime.

```sh
node -p "process.execPath"
node -p "process.platform + ' ' + process.arch"
node -p "process.report?.getReport?.().header.glibcVersionRuntime || 'no glibc version reported'"
npm ls @scope/addon
```

--------------------------------

### get_node_version signature

Source: https://napi.rs/docs/concepts/env

Gets the Node.js version information.

```rust
pub fn get_node_version(&self) -> Result<NodeVersion>
```

--------------------------------

### get_napi_version signature

Source: https://napi.rs/docs/concepts/env

Gets the N-API version (`process.versions.napi`).

```rust
pub fn get_napi_version(&self) -> Result<u32>
```

--------------------------------

### Call a Function with apply and a custom this value in Rust and TypeScript

Source: https://napi.rs/docs/concepts/function

Shows how to use `callback.apply(this, ())` to call a JavaScript callback with a specified `this` value. The Rust example defines a `RustClass` with a `name` property, and the TypeScript example demonstrates accessing `this.name` inside the callback.

```rust
use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub struct RustClass {
  pub name: String,
}

#[napi]
impl RustClass {
  #[napi(constructor)]
  pub fn new(name: String) -> Self {
    Self { name }
  }
}

#[napi]
pub fn call_function_with_apply(
  this: ClassInstance<RustClass>,
  callback: Function<(), ()>,
) -> Result<()> {
  callback.apply(this, ())
}
```

```typescript
import { callFunctionWithApply, RustClass } from './index.js'

const rustClass = new RustClass('foo')

callFunctionWithApply(rustClass, function () {
  console.log(this.name) // foo
})
```

--------------------------------

### Diagnose missing optional platform package

Source: https://napi.rs/docs/more/troubleshooting

Run these shell commands to record the detected platform and installed dependency tree when the optional platform package is missing. The output helps identify whether the installation used --no-optional, a lockfile from another platform, or missing .node/.wasm files.

```shell
node -p "process.platform + ' ' + process.arch"
npm ls your-package
find node_modules -type f \( -name '*.node' -o -name '*.wasm' \)
```

--------------------------------

### Build the addon with yarn

Source: https://napi.rs/docs/introduction/simple-package

Run the release build for your current platform using yarn. The script invokes `napi build --platform --release` and produces files like `cool.darwin-arm64.node`, `index.js`, and `index.d.ts`.

```sh
yarn build
```

--------------------------------

### Build and test NAPI-RS addon

Source: https://napi.rs/docs/introduction/manual-setup

Builds the addon and runs the test suite. The build command uses the package script that invokes napi build --platform.

```sh
npm run build
npm test
```

--------------------------------

### Require CommonJS addon

Source: https://napi.rs/docs/more/integrations

Example of requiring the CommonJS addon using require().

```js
const { add } = require('@scope/addon')
```

--------------------------------

### Using module_init and module_exports together (lib.rs and Cargo.toml)

Source: https://napi.rs/docs/concepts/module-init

This example shows how to use `#[napi_derive::module_init]` and `#[napi(module_exports)]` together in a single Rust file. The `setup_runtime` function runs once at module load to create a custom Tokio runtime (not on WASM), while `customize_exports` runs per thread to add a named property to the exports object. The accompanying Cargo.toml snippet adds the required `napi` features for async and tokio_time support.

```rust
use napi::bindgen_prelude::*;

// Runs once at module load - setup tokio runtime
#[cfg(not(target_family = "wasm"))]
#[napi_derive::module_init]
fn setup_runtime() {
  let runtime = napi::tokio::runtime::Builder::new_multi_thread()
    .enable_all()
    .build();
  match runtime {
    Ok(rt) => create_custom_tokio_runtime(rt),
    Err(err) => eprintln!("failed to create custom Tokio runtime: {err}"),
  }
}

// Runs per thread - customize exports
#[napi(module_exports)]
pub fn customize_exports(mut exports: Object) -> Result<()> {
  exports.set_named_property("THREAD_SAFE_SYMBOL", Symbol::new("THREAD_SAFE"))?;
  Ok(())
}

// Regular export via #[napi]
#[napi]
pub async fn do_async_work() -> String {
  // This uses the tokio runtime set up in module_init
  napi::tokio::time::sleep(std::time::Duration::from_millis(100)).await;
  "done".to_string()
}
```

```toml
[dependencies]
napi = { version = "3", features = ["async", "tokio_time"] }
napi-derive = "3"
```
Tokens:
Raw