Understanding N-API vs ABI: Build Efficient Node.js Native Addons with Rust

Many developers have heard of N-API and may have used C/Rust native addons, but often lack a deep understanding of the underlying ABI. This article explains what an ABI is and how it relates to N-API.

Key Points

ABI (Application Binary Interface)

An ABI defines binary‑level calling conventions and data layout, describing how programs exchange data and call functions across languages or libraries.

In simple terms, an ABI describes how a program:

Calls functions : parameter passing, return values, caller‑callee coordination.

Data layout : memory arrangement of structs, classes, arrays, etc.

Stack frame management : allocation and deallocation of stack space during calls.

Binary compatibility : ensures different compilers and platforms can interoperate.

The ABI acts as a bridge between compilers, operating systems, and hardware platforms, whereas an API operates at the source‑code level.

N‑API (Node.js API)

N‑API is a set of stable Node.js APIs for building native addons in C/C++ or other languages. Its goals are to provide a consistent interface that works across Node.js versions.

N‑API capabilities include:

Defining and managing JavaScript types (strings, objects, arrays, etc.).

Calling JavaScript functions.

Handling asynchronous operations.

Managing native memory.

Using N‑API, developers can pass data and invoke functions between JavaScript and native code, e.g., loading a compiled addon with require().

Comparing N‑API and ABI

To call a C++ library function from Node.js, you can either wrap the function with N‑API or ensure the C++ code follows the appropriate ABI (e.g., x86_64 or ARM) so that Node.js can interact with it directly.

Summary: N‑API abstracts away the low‑level ABI details, offering cross‑platform compatibility and reducing development complexity.

Implementation Examples

Below are Rust examples that implement the same functionality—returning “hello world” and an add function—using raw ABI and using N‑API.

ABI

Write lib.rs:

#[no_mangle]
pub extern "C" fn hello_world() -> *const u8 {
    "Hello, world!".as_ptr()
}

#[no_mangle]
pub extern "C" fn add(a: f64, b: f64) -> f64 {
    a + b
}

Configure Cargo.toml:

[package]
name = "rust_node_module"
version = "0.1.0"
edition = "2024"

[dependencies]

[lib]
crate-type = ["cdylib"]

Compile to a shared .node library and load it via Node.js FFI (e.g., ffi-napi) or with node-gyp for C.

N‑API

Write lib.rs using the napi crate:

use napi::{bindgen_prelude::*, Result};

#[js_function(0)]
fn hello_world(ctx: CallContext) -> Result<String> {
    Ok("Hello, world!".into())
}

#[js_function(2)]
fn add(ctx: CallContext) -> Result<f64> {
    let a = ctx.get::<f64>(0)?;
    let b = ctx.get::<f64>(1)?;
    Ok(a + b)
}

#[module_exports]
fn init(mut exports: NodeExports) -> Result<()> {
    exports.create_function("helloWorld", hello_world)?;
    exports.create_function("add", add)?;
    Ok(())
}

Configure Cargo.toml:

[package]
name = "rust_node_module"
version = "0.1.0"
edition = "2024"

[dependencies]
napi = "2.0"

[lib]
name = "my_rust_module"
crate-type = ["cdylib"]

Compile to a .node shared library and require it directly from JavaScript.

Comparison Summary

Abstraction Level : ABI requires manual memory and data handling; N‑API provides a high‑level abstraction.

Cross‑Platform Compatibility : ABI needs manual adaptation; N‑API handles differences automatically.

Memory Management : ABI is manual; N‑API automates conversion between JavaScript and Rust.

Flexibility : ABI offers fine‑grained control; N‑API offers moderate flexibility suitable for most apps.

Development Complexity : ABI is higher; N‑API simplifies development.

Performance : ABI can be optimal; N‑API adds minimal overhead but remains efficient.