NAPI-RS — Build Node.js Native Addons in Rust

Introduction

NAPI-RS is a framework for building pre-compiled Node.js native addons in Rust. It uses Node-API (N-API) for ABI stability across Node.js versions and generates TypeScript definitions automatically, making it straightforward to ship high-performance native code as a regular npm package.

What NAPI-RS Does

• Provides Rust procedural macros to export functions and structs to JavaScript
• Generates TypeScript .d.ts files automatically from Rust type signatures
• Builds pre-compiled binaries for all major platforms via GitHub Actions templates
• Supports async functions, buffers, classes, iterators, and thread-safe callbacks
• Publishes platform-specific npm packages with automatic architecture detection

Architecture Overview

NAPI-RS wraps Node-API (the stable C ABI for Node.js addons) with idiomatic Rust abstractions. The #[napi] proc macro transforms Rust functions into N-API registration entries and generates corresponding TypeScript types at compile time. The CLI scaffolds a project with Cargo.toml, npm package.json, and CI workflows that cross-compile for Linux (glibc/musl), macOS (x64/ARM), Windows, Android, and FreeBSD, then publish each as an optional npm dependency.

Self-Hosting & Configuration

• Install the CLI: npm install -g @napi-rs/cli
• Scaffold a project: napi new with target platform selection
• Write Rust functions annotated with #[napi] in src/lib.rs
• Run napi build --release to compile and generate .node and .d.ts files
• Use the generated GitHub Actions workflow for cross-platform CI builds

Key Features

• Automatic TypeScript type generation from Rust function signatures
• ABI-stable across Node.js 10+ via Node-API — no recompilation per Node version
• Pre-built binary distribution for 12+ platform/arch combinations
• Zero-copy Buffer and TypedArray support for high-throughput data processing
• Async Rust (tokio) support with automatic JS Promise bridging

Comparison with Similar Tools

• node-bindgen — similar Rust-to-Node bridge but smaller ecosystem and fewer platform targets
• Neon — Rust Node.js bindings with its own runtime; NAPI-RS uses standard Node-API for wider compatibility
• node-addon-api (C++) — official C++ wrapper for Node-API; requires manual memory management
• wasm-bindgen — compiles Rust to WebAssembly; portable but slower than native addons for CPU-heavy work
• FFI (ffi-napi) — calls shared libraries at runtime; no compile-time type safety

FAQ

Q: Do users need Rust installed to use my addon? A: No. Pre-built binaries are published to npm. End users install the package normally and the correct binary is selected automatically.

Q: Which Node.js versions are supported? A: Any version supporting Node-API (Node.js 10+). The ABI is stable so one build works across versions.

Q: Can I use async Rust with tokio? A: Yes. Annotate functions with #[napi] and return a Rust Future; NAPI-RS bridges it to a JavaScript Promise.

Q: How do I add a new target platform? A: Add the Rust target triple to napi.config.json and update the CI matrix. The CLI handles the rest.

Sources

• https://github.com/napi-rs/napi-rs
• https://napi.rs