No description
Find a file
2022-04-01 14:47:17 +08:00
.github ci: upgrade configuration 2022-04-01 14:33:34 +08:00
.husky chore: upgrade deps 2021-03-11 13:42:28 +08:00
.yarn/releases chore: upgrade dependencies 2022-03-13 18:30:11 +08:00
bench style: format toml files 2022-02-11 10:46:17 +08:00
cli ci: upgrade configuration 2022-04-01 14:33:34 +08:00
crates fix(napi): double allocation in create_buffer 2022-04-01 14:31:29 +08:00
examples feat(cli): add support for building binaries 2022-04-01 14:00:42 +08:00
images docs: add next.js into README 2021-07-30 13:14:54 +08:00
memory-testing chore: upgrade dependencies 2022-04-01 12:10:56 +08:00
triples style: run fmt 2021-12-10 16:55:55 +08:00
.cirrus.yml ci: upgrade configuration 2022-04-01 14:33:34 +08:00
.dockerignore feat(napi): support musl linux 2020-06-11 16:20:37 +08:00
.editorconfig init 2018-04-28 16:26:38 +08:00
.eslintignore feat(cli): refactor cli build 2021-11-19 18:22:40 +08:00
.eslintrc.yml feat(cli): refactor cli build 2021-11-19 18:22:40 +08:00
.gitattributes chore: upgrade to yarn3 2022-01-24 17:25:40 +08:00
.gitignore chore: upgrade to yarn3 2022-01-24 17:25:40 +08:00
.npmignore feat: support linux aarch64 2020-10-15 09:12:43 +08:00
.prettierignore chore: upgrade to yarn3 2022-01-24 17:25:40 +08:00
.yarnrc feat: upgrade to std-future 2020-02-18 21:09:17 +08:00
.yarnrc.yml chore: upgrade dependencies 2022-03-13 18:30:11 +08:00
aarch64.Dockerfile ci: build and push arm docker images 2021-10-20 11:22:17 +08:00
alpine-zig.Dockerfile feat(cli): upgrade ci.yml templates 2022-03-07 11:05:52 +08:00
alpine.Dockerfile build: install lerna in Docker images 2022-01-18 16:48:29 +08:00
armhf.Dockerfile ci: build and push arm docker images 2021-10-20 11:22:17 +08:00
ava.config.mjs fix(napi): race issues with Node.js worker_thread (#1081) 2022-03-05 14:14:32 +08:00
Cargo.toml feat(cli): add support for building binaries 2022-04-01 14:00:42 +08:00
CODE_OF_CONDUCT.md doc: add email to CODE_OF_CONDUCT 2020-05-20 18:49:36 +08:00
debian-zig.Dockerfile feat(cli): upgrade ci.yml templates 2022-03-07 11:05:52 +08:00
debian.Dockerfile ci: pin llvm clang versions 2022-02-07 23:33:57 +08:00
generate-triple-list.ts feat(cli): refactor cli build 2021-11-19 18:22:40 +08:00
lerna.json @napi-rs/cli@1.0.0-alpha.12 2020-12-23 22:46:48 +08:00
LICENSE docs: update license 2021-01-25 14:12:44 +08:00
package.json feat(cli): add support for building binaries 2022-04-01 14:00:42 +08:00
README.md chore: remove node10 test 2022-01-04 11:14:55 +08:00
renovate.json chore: remove node10 test 2022-01-04 11:14:55 +08:00
rollup.config.js fix(cli): compatible for Node.js 10x 2022-02-09 12:41:56 +08:00
rustfmt.toml feat(cli): refactor cli build 2021-11-19 18:22:40 +08:00
tsconfig.json fix(napi-derive): BigInt in TypeScript should be bigint 2022-01-06 22:33:34 +08:00
tsconfig.root-lint.json ci: add memory leak detect job 2021-05-29 23:24:25 +08:00
yarn.lock feat(cli): add support for building binaries 2022-04-01 14:00:42 +08:00

napi-rs

Stake to support us chat

This project was initialized from xray

A minimal library for building compiled Node.js add-ons in Rust.

Main branch is now under napi@next developing. Checkout v1 docs for napi@1.x.

Ecosystem

Prisma     swc     Parcel   next.js   nextjs.svg

Platform Support

Lint Linux musl macOS/Windows/Linux x64 Linux-aarch64 Linux-armv7 macOS-Android Android-armv7 Windows i686 Windows arm64 FreeBSD

MSRV

Rust 1.57.0

node12 node14 node16 node17
Windows x64
Windows x86
Windows arm64
macOS x64
macOS aarch64
Linux x64 gnu
Linux x64 musl
Linux aarch64 gnu
Linux aarch64 musl
Linux arm gnueabihf
Linux aarch64 android
Linux armv7 android
FreeBSD x64

This library depends on Node-API and requires Node@10.0.0 or later.

We already have some packages written by napi-rs: node-rs

One nice feature is that this crate allows you to build add-ons purely with the Rust/JavaScript toolchain and without involving node-gyp.

Taste

You can start from package-template to play with napi-rs

Define JavaScript functions

#[macro_use]
extern crate napi;

/// import the preludes
use napi::bindgen_prelude::*;

/// module registration is done by the runtime, no need to explicitly do it now.
#[napi]
fn fibonacci(n: u32) -> u32 {
  match n {
    1 | 2 => 1,
    _ => fibonacci(n - 1) + fibonacci(n - 2),
  }
}

/// use `Fn`, `FnMut` or `FnOnce` traits to defined JavaScript callbacks
/// the return type of callbacks can only be `Result`.
#[napi]
fn get_cwd<T: Fn(String) -> Result<()>>(callback: T) {
  callback(env::current_dir().unwrap().to_string_lossy().to_string()).unwrap();
}

/// or, define the callback signature in where clause
#[napi]
fn test_callback<T>(callback: T)
where T: Fn(String) -> Result<()>
{}

/// async fn, require `async` feature enabled.
/// [dependencies]
/// napi = {version="2", features=["async"]}
#[napi]
async fn read_file_async(path: String) -> Result<Buffer> {
  tokio::fs::read(path)
    .map(|r| match r {
      Ok(content) => Ok(content.into()),
      Err(e) => Err(Error::new(
        Status::GenericFailure,
        format!("failed to read file, {}", e),
      )),
    })
    .await
}

more examples at examples

Building

This repository is a Cargo crate. Any napi-based add-on should contain Cargo.toml to make it a Cargo crate.

In your Cargo.toml you need to set the crate-type to "cdylib" so that cargo builds a C-style shared library that can be dynamically loaded by the Node executable. You'll also need to add this crate as a dependency.

[package]
name = "awesome"

[lib]
crate-type = ["cdylib"]

[dependencies]
napi = "2"
napi-derive = "2"

[build-dependencies]
napi-build = "1"

And create build.rs in your own project:

// build.rs
extern crate napi_build;

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

So far, the napi build script has only been tested on macOS Linux Windows x64 MSVC and FreeBSD.

Install the @napi-rs/cli to help you build your Rust codes and copy Dynamic lib file to .node file in case you can require it in your program.

{
  "package": "awesome-package",
  "devDependencies": {
    "@napi-rs/cli": "^1.0.0"
  },
  "napi": {
    "name": "jarvis" // <----------- Config the name of native addon, or the napi command will use the name of `Cargo.toml` for the binary file name.
  },
  "scripts": {
    "build": "napi build --release",
    "build:debug": "napi build"
  }
}

Then you can require your native binding:

require('./jarvis.node')

The module_name would be your package name in your Cargo.toml.

xxx => ./xxx.node

xxx-yyy => ./xxx_yyy.node

You can also copy Dynamic lib file to an appointed location:

napi build [--release] ./dll
napi build [--release] ./artifacts

There are documents which contains more details about the @napi-rs/cli usage.

Testing

Because libraries that depend on this crate must be loaded into a Node executable in order to resolve symbols, all tests are written in JavaScript in the test_module subdirectory.

To run tests:

yarn build:test
yarn test

Features table

Rust Type Node Type NAPI Version Minimal Node version Enable by napi feature
u32 Number 1 v8.0.0
i32/i64 Number 1 v8.0.0
f64 Number 1 v8.0.0
bool Boolean 1 v8.0.0
String/&'a str String 1 v8.0.0
Latin1String String 1 v8.0.0 latin1
UTF16String String 1 v8.0.0
Object Object 1 v8.0.0
serde_json::Map Object 1 v8.0.0 serde-json
serde_json::Value any 1 v8.0.0 serde-json
Array Array 1 v8.0.0
Vec Array 1 v8.0.0
Buffer Buffer 1 v8.0.0
External External 1 v8.0.0
Null null 1 v8.0.0
Undefined/() undefined 1 v8.0.0
Result<()> Error 1 v8.0.0
T: Fn(...) -> Result Function 1 v8.0.0
Async/Future Promise 4 v10.6.0 async
AsyncTask Promise 1 v8.5.0
JsGlobal global 1 v8.0.0
JsSymbol Symbol 1 v8.0.0
Int8Array/Uint8Array ... TypedArray 1 v8.0.0
JsFunction threadsafe function 4 v10.6.0 napi4
BigInt BigInt 6 v10.7.0 napi6