14 releases (stable)

4.3.0 Mar 15, 2021
4.1.0 Dec 24, 2020
4.0.0 Nov 20, 2020
3.0.0 Oct 15, 2020
0.1.2 Mar 9, 2020
Download history 22/week @ 2021-02-25 20/week @ 2021-03-04 62/week @ 2021-03-11 30/week @ 2021-03-18 189/week @ 2021-03-25 207/week @ 2021-04-01 111/week @ 2021-04-08 151/week @ 2021-04-15 45/week @ 2021-04-22 73/week @ 2021-04-29 84/week @ 2021-05-06 94/week @ 2021-05-13 74/week @ 2021-05-20 87/week @ 2021-05-27 131/week @ 2021-06-03 203/week @ 2021-06-10

371 downloads per month


1.5K SLoC


Easy way to write native Node.js module using idiomatic Rust


  • Easy: Just write idiomatic Rust code, node-bindgen take care of generating Node.js FFI wrapper codes.
  • Safe: Node.js arguments are checked automatically based on Rust types.
  • Async: Support Async Rust. Async codes are translated into Node.js promises.
  • Class: Rust struct can be accessed using Node.js classes.
  • Stream: Implement Node.js stream using Rust
  • N-API: Use Node.js N-API, which means you don't have to recompile your module.

Compatibility with Node.js version

This project uses the v7 of Node N-API. Please see following compatibility matrix.

Following OS are supported:

  • Linux
  • MacOs
  • Windows

Why node-bindgen?

Writing native node-js requires lots of boilerplate code. Node-bindgen generates external "C" glue code from rust code, including native module registration. node-bindgen make it writing node-js module easy and fun.

Getting started

CLI Installation

Install nj-cli command line, which will be used to generate the native library.

cargo install nj-cli

This is one time step.

Configuring Cargo.toml

Add two dependencies to your projects' Cargo.toml.

Add node-bindgen as a regular dependency (as below):

node-bindgen = { version = "4.0" }

Then add node-bindgen's procedure macro to your build-dependencies as below:

node-bindgen = { version = "4.0", features = ["build"] }

Then update crate type to cdylib to generate node.js compatible native module:

crate-type = ["cdylib"]

Finally, add build.rs at the top of the project with following content:

fn main() {


Here is a function that adds two numbers. Note that you don't need to worry about JS conversion.

use node_bindgen::derive::node_bindgen;

/// add two integer
fn sum(first: i32, second: i32) -> i32 {
    first + second

Building native library

To build node.js library, using nj-cli to build:

nj-cli build

This will generate Node.js module in "./dist" folder.

To build a release version:

nj-cli build --release

Watching ./src for Changes

While developing your native module, you may want to watch for file changes and run a command when a change occurs, for example cargo check or cargo build.

For this, we can use nj-cli watch.

nj-cli watch installs [if it does not exist] and passes arguments to cargo watch. By default, nj-cli watch will run cargo check against your ./src files.

To see all available methods for nj-cli watch, run the following command:

nj-cli watch -- --help

Using in Node.js

Then in the Node.js, rust function can be invoked as normal node.js function:

$ node
Welcome to Node.js v14.0.0.
Type ".help" for more information.
> let addon = require('./dist');
> addon.sum(2,3)


Function name or method can be renamed instead of default mapping

fn mul(first: i32,second: i32) -> i32 {
    first * second

Rust function mul is re-mapped as multiply

Optional argument

Argument can be skipped if it is marked as optional

fn sum(first: i32, second: Option<i32>) -> i32 {
    first + second.unwrap_or(0)

Then sum can be invoked as sum(10) or sum(10,20)


JS callback are mapped as Rust closure.

fn hello<F: Fn(String)>(first: f64, second: F) {

    let msg = format!("argument is: {}", first);


from node:

let addon = require('./dist');

  assert.equal(msg,"argument is: 2");
  console.log(msg);  // print out argument is 2

Callback are supported in Async rust as well.

Support for Async Rust

Async rust function is mapped to Node.js promise.

use std::time::Duration;
use flv_future_aio::time::sleep;
use node_bindgen::derive::node_bindgen;

async fn hello(arg: f64) -> f64 {
    println!("woke and adding 10.0");
    arg + 10.0
let addon = require('./dist');

addon.hello(5).then((val) => {
  console.log("future value is %s",val);

JavaScript class

JavaScript class is supported.

struct MyClass {
    val: f64,

impl MyClass {

    fn new(val: f64) -> Self {
        Self { val }

    fn plus_one(&self) -> f64 {
        self.val + 1.0

    fn value(&self) -> f64 {
let addon = require('./dist');
const assert = require('assert');

let obj = new addon.MyObject(10);
assert.equal(obj.value,10,"verify value works");

There are more features in the examples folder.

Windows + Electron Support

When using node-bindgen with electron on Windows, nj-build must compile a C++ file, win_delay_load_hook.cc, and therefore it is required that the development environment has a valid C/C++ compiler.

If your machine does not have a valid C/C++ compiler, install Microsoft VSCode.

In the future, this file will be re-written in Rust, removing this dependency.


If you'd like to contribute to the project, please read our Contributing guide.


This project is licensed under the Apache license.


~86K SLoC