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

> Write high-performance Node.js native modules in Rust with automatic TypeScript type generation and cross-platform prebuilt binaries.

## Install

Save as a script file and run:

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

## Quick Use
```bash
npm install -g @napi-rs/cli
napi new my-addon
cd my-addon
npm run build
node -e "const addon = require('./index.node'); console.log(addon.sum(1, 2))"
```

## 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

---
Source: https://tokrepo.com/en/workflows/d4235392-4211-11f1-9bc6-00163e2b0d79
Author: Script Depot