Native Add-ons, WebAssembly & FFI

An Application Binary Interface (ABI) is the compiled counterpart of an API: it fixes names, argument layouts and structure sizes at the machine level. Node.js commits to a stable ABI across the minor and patch releases of one major, and Node-API extends that promise across majors: an add-on compiled once against Node-API loads in later major versions without recompilation. The Learn guide spells out why it matters: a package written only in JavaScript survives a new Node.js major untouched, while a package with a V8-based add-on has to be recompiled, reinstalled and redeployed. The version matrix in the API documentation adds a refinement. Up to Node-API 8 each version was a superset of the previous one. From version 9 on, an add-on that works with version 9 may need code changes for version 10, so Node.js defaults to the version 8 interface unless the add-on opts in with the NAPI_VERSION macro, which is baked into the binary at build time.

The smallest useful add-on for the Bookshelf application validates ISBN-10 check digits. Three files describe it: the C source, the binding.gyp build description, and a package.json that marks the package as having a native build. Node-API needs only one header, node_api.h, and no dependency from npm.

Source: Node-API (C/C++ addons with Node-API)

Every Node-API call returns a napi_status, and the function must not continue as if a failed call had succeeded. The buffer is a fixed 16 bytes and napi_get_value_string_utf8 truncates to its size, so an over-long input can never overflow it; reading a length first with a null buffer is the pattern to use when the size is unknown. The example was compiled and run; it was not fuzzed, and it is a teaching example, not a hardened parser.

Source: Node-API build tools: node-gyp

node-gyp is the default build tool: npm bundles it (version 12.4.0 inside npm 11.19.x on Node.js 26 and 24, version 11.5.0 inside npm 10.9.9 on Node.js 22, as observed), and it drives the platform compiler (Xcode command line tools on macOS, a C and C toolchain on Linux, Visual Studio Build Tools on Windows); the Learn guide's tools page lists a C/C compiler and Python as requirements of node-gyp. If a package has a binding.gyp in its root and defines no install or preinstall script, npm install runs node-gyp rebuild by itself. It first downloads the Node.js headers for the running version, which is why the first build needs network access. The build below ran with Node.js 24.

Source: npm scripts: life cycle operation order, node-gyp default

CMake.js is the alternative for projects that already use CMake. It is based on the CMake tool, which must be installed, and the Learn guide lists its cons as being less widely adopted in the Node.js community. CMake was not installed in the environment used to write this page, so the following file was not executed; it adapts the Learn guide’s template to the same C source.

Source: Node-API build tools: CMake.js

The package then declares "install": "cmake-js compile" and a development dependency on cmake-js. The third tool in the Learn guide, node-pre-gyp, adds distribution of pre-built binaries (downloaded from an object store) on top of node-gyp, so users without a compiler can still install the package. The Learn guide contrasts two strategies: compile on the user’s machine at install time, which is simple but requires a working toolchain for every user, or publish pre-built binaries per platform and architecture and fall back to compiling. A package with a native dependency tree is the usual reason an installation fails on a new machine or a new Node.js major, so the second strategy is worth the effort for anything published; Workspaces & Publishing covers what publishing adds for Node packages in general, and the Learn page on publishing Node-API packages explains how to publish a Node-API version next to a legacy one with an npm dist-tag.

Node.js recognises the .node extension in the CommonJS loader, so require('./build/Release/isbn.node') initialises the library, and the extension can usually be omitted. From an ES module, use module.createRequire(). The lowest-level entry point, process.dlopen(module, filename), is what the loader calls and is occasionally useful when a path is computed.

Source: C++ addons: loading addons using require() and import

index.js here is a single line: module.exports = require('./build/Release/isbn.node');.

Source: Learn: ABI Stability

process.versions.modules is the engine ABI number that changes with every major (127, 137, 147 here). A V8-based add-on built for one of those numbers is refused by the others; the Node-API add-on above never cared, which is the whole point. As for import, the observed behaviour on 26.10.0 and 24.21.0 was that import('./build/Release/isbn.node') resolved to a module whose default and 'module.exports' exports are the add-on’s exports, with an ExperimentalWarning; on 22.23.3 it needed --experimental-addon-modules. Since the add-ons page, the CLI reference and the ES modules page disagree about the status, keep createRequire in anything that has to run on all three lines.

Writing every call against the C API is tedious and error-prone, so most projects use node-addon-api, a header-only C wrapper published on npm (version 8.9.2 resolved when this page was written). It turns `napi_value` handles into `Napi::Value`, `Napi::String` and friends, and offers `Napi::ObjectWrap` to expose a C class as a JavaScript class. It is still Node-API underneath, so the ABI stability applies. NAPI_DISABLE_CPP_EXCEPTIONS below keeps the build exception-free, and errors are raised with ThrowAsJavaScriptException().

Source: Learn: Getting Started with Node-API (node-addon-api)

With "dependencies": { "node-addon-api": "^8.0.0" } in package.json, npm install built the add-on on Node.js 26; require('./').slugify('Dune Messiah!') returned dune-messiah there and on Node.js 22 with the same binary, and passing a number raised TypeError: slugify(title) needs a string. The string is converted to UTF-8 and the loop only handles ASCII letters and digits, so a title written in another script is reduced to dashes. Real code needs a proper transliteration library.

Two limits of the examples above deserve a mention because real add-ons hit them quickly. Both functions run synchronously on the JavaScript thread, so a slow native function blocks the event loop exactly as slow JavaScript would (see Don’t Block the Event Loop). Moving work to a thread and returning a promise or calling back from another thread are covered by the Node-API special topics in the Learn guide: asynchronous work, thread-safe functions, context awareness (an add-on may be loaded more than once, including inside worker threads) and object and function references.

A native add-on runs with all the privileges of the Node.js process and can corrupt its memory; nothing in Node.js sandboxes it. For that reason two switches exist. --no-addons turns add-on loading off, and with the permission model, --permission refuses add-ons unless --allow-addons is also passed. Observed on 26.10.0 with the add-on above: node --permission --allow-fs-read="$PWD" check.mjs failed with Error: Cannot load native addon because loading addons is disabled., and adding --allow-addons worked but printed a SecurityWarning that the flag must be used with extreme caution, because it can invalidate the permission model. node --no-addons check.mjs failed with ERR_DLOPEN_DISABLED. See Security Best Practices for the supply-chain side: a dependency that downloads or compiles binaries at install time deserves the same scrutiny as any lifecycle script.

The shortest possible example embeds a hand-assembled module (the bytes of (func (export "add") (param i32 i32) (result i32) local.get 0 local.get 1 i32.add)) so that nothing has to be installed. WebAssembly.validate() checks bytes without compiling them, WebAssembly.instantiate() compiles and instantiates, and exported functions appear under instance.exports.

Source: Learn: Node.js with WebAssembly

The output (true, 11, -2147483648) was identical on Node.js 26, 24 and 22. The last line shows the boundary to keep in mind: WebAssembly integers are fixed-width, so i32 arithmetic wraps where a JavaScript number would not. In practice nobody writes bytes by hand; the Learn guide lists four ways to produce a module: writing the text format (.wat) and converting it with the wabt tools, compiling C or C++ with Emscripten, compiling Rust with wasm-pack, or writing AssemblyScript, a TypeScript-like language.

Numbers cross the boundary directly; anything else (strings, arrays, records) travels through the module’s linear memory, and the host and the module must agree on the layout. The next module imports a JavaScript function (env.log), exports its memory, and sums a range of bytes in it. It is written in the text format so that the logic is readable.

Convert it with wat2wasm sum.wat -o sum.wasm (from the WebAssembly Binary Toolkit, wabt). In the environment used here the command line tool was not installed, so the same conversion was done through the wabt package from npm (version 1.0.39) in a scratch project; the resulting 112-byte file is what the next script loads.

Source: Learn: Node.js with WebAssembly (generating modules with wabt)

Source: Learn: Node.js with WebAssembly

The output was wasm says total = 100, 100, 65536 (observed on 26). A view created from memory.buffer is invalidated when the module grows its memory, so re-create views after any call that might allocate. Tools such as Emscripten and wasm-pack generate this glue (string encoding, allocation, error handling) for you, which is usually better than writing it by hand.

Node.js can also load .wasm files through the module system. Since v24.5.0 and v22.19.0 this no longer needs --experimental-wasm-modules. A module with no imports of its own can be imported like any other (the instance phase, Stability 1.1), and the exports become named exports. import source (the source phase, Stability 1.2 and added in v24.0.0) gives you the compiled WebAssembly.Module so that you can create several instances or pass custom imports.

Source: Modules: ECMAScript modules, Wasm modules

Observed: esm-import.mjs printed 42 and an ExperimentalWarning ("Importing WebAssembly module instances is an experimental feature") on Node.js 26, 24 and 22. src-phase.mjs printed true 0 on 26 and 24, and failed with a syntax error on 22. Two further rules from the module documentation: module and export names that start with wasm-js: are reserved, and wasm: is reserved for export names and imported module names (since v24.5.0 and v22.19.0). The wasm:js-string compile-time builtins mentioned in the same page are an advanced feature that this page does not use.

The example uses a three-function library compiled from C. Its source is part of the example because the signatures must match it exactly.

Source: FFI: Overview and signature objects

Source: FFI: ffi.dlopen() and signature objects

Observed on 26.10.0: an ExperimentalWarning: FFI is an experimental feature and might change at any time, then 42 and 4n. The using declaration works because the object returned by dlopen() implements the explicit resource management protocol and closes the library when the block ends. ffi.suffix is 'dylib' on macOS, 'so' on Unix-like systems and 'dll' on Windows, which keeps the path portable. Signature objects use type names such as int32, uint64, float64, pointer, string, buffer and arraybuffer (with short aliases like i32, f64 and ptr), and 64-bit integers cross as bigint.

library.registerCallback() creates a native function pointer backed by a JavaScript function, and library.getFunction() resolves one symbol at a time. The restrictions are strict: a callback must be invoked on the thread that created it, must not throw, must not return a promise, must return a value compatible with its declared type, and must not close its library or unregister itself while it runs. Native code must stop using a callback address before the callback is unregistered or the library closed; calling a stale pointer is undefined behaviour.

Source: FFI: library.registerCallback() and Calling native functions

The output was 20 on 26.10.0. When a Buffer is passed as a pointer-like argument, Node.js borrows the raw pointer to its backing memory for the duration of the call, so the buffer must not be resized, transferred or detached during that call, including from a callback. The module also has memory helpers (ffi.toString(), ffi.toBuffer(), ffi.toArrayBuffer(), the ffi.export* functions and ffi.getRawPointer()); the documentation advises preferring copied values unless zero-copy access is required. Passing null to dlopen() resolves symbols from the running process, which is enough to call a libc function such as getpid:

Source: FFI: ffi.dlopen(path[, definitions)]

null is not supported on Windows. Observed: it printed true on macOS with Node.js 26. FFI calls that fit a platform-specific trampoline use an optimised Fast FFI path (at most 8 arguments, with register limits that differ per architecture; the documentation tabulates them), and everything else falls back to a generic path, so benchmark your own signature before assuming a speed-up.

With --permission, the FFI APIs are restricted unless --allow-ffi is passed (Stability 1.1, added in v26.1.0). Observed on 26.10.0: node --permission --allow-fs-read="$PWD" call.mjs failed with ERR_ACCESS_DENIED ("Use --allow-ffi to manage permissions"), and adding --allow-ffi printed a SecurityWarning about extreme caution plus the normal output. The warning is accurate: once a process may load arbitrary libraries and call arbitrary symbols, it can do anything the user can do, so the permission model’s file and network limits no longer constrain it.