Typorithm · hard

N-API / C++ Addons

napi-addonarchitecturen-apiaddonnode-gyp

Saved on this device

Full lesson · 8 learning steps Open any exercise for focused practice

Step 1 of 8 · intro card

Learn N-API / C++ Addons

Native Integrations

Node can require a compiled .node addon written in C/C++. N-API is the ABI-stable C interface so an addon keeps working across Node major versions without recompilation; binding.gyp declares the build and node-gyp rebuild compiles it. Use addons for CPU-bound work or to wrap an existing native library, mindful that each JS↔native call has a cost.

A native addon is a shared library (with a .node extension) compiled from C or C++. Node loads it with the same require() you use for any module; the difference is that the exported functions are machine code, not JavaScript.

N-API (node-api) is the key architectural piece: it is an ABI-stable C interface against which the addon links. Because the ABI is frozen, a single compiled .node binary keeps working across Node major versions — without N-API you would relink against V8's internals and recompile for every release.

The build is declared in binding.gyp, and node-gyp rebuild compiles the sources into the addon. Reach for addons when you need raw CPU speed or must wrap an existing C/C++ library — but remember each call across the JS↔native boundary carries overhead, so batch work rather than crossing in a tight loop.

require() loads a compiled .node addon.

N-API is the ABI-stable C interface across Node versions.

binding.gyp + node-gyp rebuild build the addon.

const addon = require("./build/Release/addon.node");

const sum = addon.add(2, 3);
console.log(sum);

// built from binding.gyp with: node-gyp rebuild

Read the implementation

Connect each part of the code to the concept before you type.

1. Load the addon

Node loads a compiled .node file with require(), just like any other module — the addon is native machine code.

const addon = require("./build/Release/addon.node");

2. Call native code

Calling addon.add crosses the JS→native boundary; the C++ function runs, then the result is marshalled back to a JS number.

const sum = addon.add(2, 3);

3. Use the result

From JavaScript's side the native result is an ordinary value — the boundary crossing is invisible to the caller.

console.log(sum);

4. How it is built

binding.gyp declares the build, and node-gyp rebuild compiles the C++ into the .node addon.

// built from binding.gyp with: node-gyp rebuild

A complete learning loop

Understand

Read the concept map and follow the code breakdown.

Reconstruct

Type the implementation, repair mistakes and work through every recall exercise.

Verify

Use the final check without hints; revisit weak concepts in short practice sessions.