Building Node.js Modules with Rust and NAPI-RS

Why Rust for Node.js Modules?

Modern web applications increasingly demand high-performance compute capabilities that pure JavaScript cannot efficiently provide. Whether you're processing images, performing cryptographic operations, or running machine learning inference, the performance bottlenecks of the JavaScript runtime can become limiting factors.

Rust and NAPI-RS offer a powerful solution: the ability to write high-performance native modules in Rust that seamlessly integrate with your web development services. This approach brings Rust's memory safety guarantees and computational efficiency to the JavaScript ecosystem, enabling developers to build lightning-fast web applications while maintaining the developer experience they love. For applications requiring both high performance and intelligent automation, combining Rust native modules with our AI automation services creates a powerful technical foundation.

Getting Started with NAPI-RS

Installing the CLI

The @napi-rs/cli tool provides an interactive project creation experience that handles all the boilerplate configuration for you. Install it globally using your preferred package manager:

# Using yarn
yarn global add @napi-rs/cli

# Using npm
npm install -g @napi-rs/cli

# Using pnpm
pnpm add -g @napi-rs/cli

Creating Your First Project

Run the interactive CLI to scaffold your project:

napi new

The CLI will prompt you for:

• Package name: Your npm package name (recommended to use npm scope)
• Target platforms: Select the platforms you want to support
• GitHub Actions: Enable automated CI/CD for publishing

Project Structure

The generated project includes:

my-project/
├── Cargo.toml # Rust dependency configuration
├── build.rs # Build script for napi-rs
├── src/
│ └── lib.rs # Your Rust module code
├── npm/ # Platform-specific packages
├── .github/
│ └── workflows/
│ └── CI.yml # Auto-generated CI/CD workflow
└── package.json # npm package configuration

Writing Your First Native Function

The #[napi] macro makes it trivial to expose Rust functions to JavaScript. Here's a complete example:

use napi::bindgen_prelude::*;

#[napi]
pub fn add(a: i32, b: i32) -> i32 {
 a + b
}

#[napi]
pub fn fibonacci(n: u32) -> u64 {
 if n <= 1 {
 n as u64
 } else {
 fibonacci(n - 1) + fibonacci(n - 2)
 }
}

#[napi]
pub fn process_buffer(buffer: Buffer) -> Result<Buffer> {
 // Process binary data efficiently
 let data = buffer.to_vec();
 // ... perform operations ...
 Ok(data.into())
}

Use these functions in JavaScript just like any other module:

const { add, fibonacci } = require('@company/my-native-module');

console.log(add(5, 3)); // 8
console.log(fibonacci(20)); // 6765

Type Conversions

NAPI-RS automatically handles conversions between Rust and JavaScript types:

Building Classes and Objects

Expose Rust structs as full JavaScript classes with methods, getters, and constructors:

use napi::{bindgen_prelude::*, Result};
use serde::{Deserialize, Serialize};

#[napi]
#[derive(Serialize, Deserialize)]
pub struct User {
 pub id: u32,
 pub name: String,
 pub email: String,
}

#[napi]
impl User {
 #[napi(constructor)]
 pub fn new(id: u32, name: String, email: String) -> Result<Self> {
 Ok(Self { id, name, email })
 }

 #[napi(getter)]
 pub fn display_name(&self) -> String {
 format!("{} ({})", self.name, self.id)
 }

 #[napi(method)]
 pub fn update_email(&mut self, new_email: String) {
 self.email = new_email;
 }

 #[napi(js_name = "isValid")]
 pub fn is_valid(&self) -> bool {
 !self.email.is_empty() && self.id > 0
 }
}

Use in JavaScript:

const { User } = require('@company/my-native-module');

const user = new User(1, 'John Doe', '[email protected]');
console.log(user.displayName); // "John Doe (1)"
user.updateEmail('[email protected]');
console.log(user.isValid); // true

Multi-Platform Distribution

NAPI-RS simplifies cross-platform distribution by generating separate npm packages for each target. When you select multiple platforms during project creation, the CLI creates:

@company/my-utils/ # Main package (JavaScript loader)
├── index.js # Platform detection & binary loading
└── package.json # optionalDependencies to platform packages

@company/my-utils-darwin-x64/ # macOS x64
├── package.json # os: ["darwin"], cpu: ["x64"]
└── my_utils.darwin-x64.node # Compiled binary

@company/my-utils-darwin-arm64/ # macOS ARM (Apple Silicon)
├── package.json
└── my_utils.darwin-arm64.node

@company/my-utils-win32-x64/ # Windows x64
├── package.json
└── my_utils.win32-x64.node

@company/my-utils-linux-x64-gnu/ # Linux glibc
├── package.json
└── my_utils.linux-x64-gnu.node

@company/my-utils-linux-arm64-gnu/ # Linux ARM64
├── package.json
└── my_utils.linux-arm64-gnu.node

The auto-generated index.js handles platform detection and loads the correct binary automatically.

Integration with Next.js Applications

Native modules integrate seamlessly with Next.js. Here's how to use them effectively:

// lib/native-utils.ts
import { add, fibonacci, User } from '@company/native-utils';

// Server-side calculation
export function calculateSum(a: number, b: number): number {
 return add(a, b);
}

// Performance-critical computation
export function getFibonacci(n: number): number {
 return fibonacci(n);
}

// Data processing
export function createUser(id: number, name: string, email: string) {
 return User.new(id, name, email);
}

Usage in API Routes

// app/api/calculate/route.ts
import { calculateSum } from '@/lib/native-utils';

export async function POST(request: Request) {
 const { a, b } = await request.json();
 const result = calculateSum(a, b);
 return Response.json({ result });
}

To maximize performance in your Next.js application, consider pairing native modules with advanced caching strategies for optimal throughput.

Configuration Notes

• Native modules work in Server Components and API routes
• For Client Components, ensure the module is dynamically imported
• Some deployment platforms (like Vercel) may have restrictions on native modules
• Consider using Edge Runtime for maximum compatibility

Best Practices and Common Pitfalls

Error Handling

Always return Result<T> from functions that might fail, and use napi-rs's error types:

use napi::{Error, Result};

#[napi]
pub fn parse_json(content: String) -> Result<serde_json::Value> {
 serde_json::from_str(&content)
 .map_err(|e| Error::new(Status::InvalidArg, e.to_string()))
}

Memory Management

• Let Rust's ownership model work naturally--avoid holding references across FFI boundaries
• Use Buffer types for large binary data to avoid copying
• Implement Drop traits for resource cleanup when needed

Testing

#[cfg(test)]
mod tests {
 use super::*;

 #[test]
 fn test_add() {
 assert_eq!(add(2, 3), 5);
 }

 #[test]
 fn test_fibonacci() {
 assert_eq!(fibonacci(10), 55);
 }
}

Run tests with: cargo test

Sources

1. NAPI-RS Official Documentation
2. Building Node.js Modules in Rust with NAPI-RS - LogRocket
3. NAPI-RS GitHub Organization
4. NAPI-RS Documentation - Concepts