napi-rs

napi-rs is a Rust framework for building native Node.js add-ons through Node-API (N-API), the ABI-stable interface for native modules. It replaces the traditional node-gyp toolchain with a pure Rust/JavaScript workflow: write functions annotated with the #[napi] macro from the napi-derive crate, and the napi crate handles marshalling Rust types to and from JavaScript values, async/Promise interop, threadsafe callbacks, and error propagation.

The project ships as a coordinated set of crates (napi, napi-derive, napi-sys, napi-build) plus the @napi-rs/cli npm package, which drives cross-compilation and packaging for every supported platform triple (Windows, macOS, Linux glibc/musl, Android, FreeBSD, across x64/arm64/armv7/riscv64/loongarch64). This lets library authors ship a single npm package that resolves to the correct prebuilt .node binary at install time, with no compiler required on the consumer’s machine.

What You Get

• The #[napi] proc-macro attribute for exposing Rust functions, structs, classes, and enums directly to JavaScript with automatic type marshalling
• First-class async support: Rust async fn becomes a JavaScript Promise, with a pluggable async-runtime SPI so a tokio-free build is possible
• Threadsafe function support for calling back into JavaScript from any Rust thread, plus Buffer/TypedArray/BigInt/Symbol bridging
• The @napi-rs/cli tool for building, cross-compiling, and packaging release binaries for 15+ platform triples in one command
• A napi-build build-script helper that wires up the Node-API linking flags automatically
• Companion packages (@napi-rs/triples, @napi-rs/wasm-runtime) for platform-triple resolution and optional WebAssembly fallback

Common Use Cases

• Wrapping a performance-critical Rust library (parsing, cryptography, image/video processing) as a drop-in npm package for Node.js consumers
• Building CPU-bound native modules that need true multithreading without Node’s single-threaded event loop constraints
• Publishing cross-platform npm packages that ship prebuilt binaries instead of requiring consumers to compile from source
• Migrating an existing node-gyp/C++ native addon to a memory-safe Rust implementation with less boilerplate

Under The Hood

Architecture - The repo is a Cargo workspace split into five crates under crates/: napi (the public runtime API — value conversion, environment handling, error types), macro (the napi-derive proc-macro crate that expands #[napi] attributes into N-API registration code at compile time), backend (shared codegen logic consumed by the macro), sys (raw napi-sys FFI bindings to the Node-API C headers), and build (the napi-build build-script helper that emits the correct linker flags). The cli directory holds the separately-versioned @napi-rs/cli npm package, written in TypeScript/Rust, which orchestrates cargo build, cross-compilation via target triples, and packaging of the resulting .node binary plus generated .d.ts files. triples and wasm-runtime are satellite npm packages for platform-triple resolution and an optional WASM fallback path. Tech Stack - Core crates target Rust edition 2021 with a workspace-pinned MSRV of 1.88.0; the async feature pulls in tokio_rt while an async-runtime feature keeps a tokio-free path available via a pluggable AsyncRuntime SPI. The JS/TS side uses Lerna for cross-package versioning and Yarn as the package manager. CI (GitHub Actions) runs an address-sanitizer workflow and a dedicated memory-leak-detection workflow (memory-testing/Cargo.toml) on every push, alongside the standard test-and-release pipeline across 15+ platform triples. Code Quality - Because native addons must run inside a Node process to resolve N-API symbols, tests live in JavaScript under test_module and exercise the compiled binary end-to-end rather than as pure Rust unit tests; this is a deliberate, documented trade-off rather than an absence of testing. The crate exposes a compat-mode feature flag specifically to preserve backward compatibility for deprecated types/traits, showing an explicit deprecation discipline. Naming is consistent throughout (napi_* for FFI, Napi* for public Rust types). API Design - The #[napi] attribute macro is the entire public surface for exposing a function, struct, class, or enum to JavaScript, and it also generates the matching .d.ts declarations automatically — getting from a plain Rust function to a callable, typed JS export requires a single attribute line and a Cargo.toml/build.rs boilerplate pair, which is a very low-friction entry point for an FFI-generation framework of this scope.