nodejs/node-addon-examples: a reference set of Node.js C++ addon examples

What nodejs/node-addon-examples is for

Writing a C++ addon for Node.js means choosing between several APIs that all reach the same V8 internals by different routes. The documentation describes four of them: nan, a C++ abstraction over direct V8 APIs; Node-API, a C API that guarantees ABI stability across Node.js versions and JavaScript engines; node-addon-api, a header-only C++ wrapper over Node-API; and the Napi::Addon class variant of node-addon-api. The repository exists to show what each looks like in practice, side by side, for the same small task.

That makes it useful in two situations. The first is orientation: you have never written an addon and want to see the smallest possible one before committing to an API. The second is comparison: you already know you need native code and want to see how a callback, an async worker or a threadsafe function is expressed in each style. The README points readers who want guided orientation rather than raw examples to the Node-API Resource site.

The repository is not a library. There is no package to depend on and no release history; the package.json at the root exists to drive the test runner and formatting tooling for the examples themselves.

How the examples are laid out

The tree is organised first by concept, then by implementation. The README gives the structure explicitly, with directories numbered from 1-getting-started through 8-tooling, covering JavaScript-to-native conversion, context awareness, references and handle scope, async work, threadsafe functions, events and tooling.

Inside a numbered concept directory, each example has one subdirectory per implementation. So a single example can appear three times, once under nan, once under napi and once under node-addon-api. That repetition is the point: the same behaviour, three source files, three sets of trade-offs. Implementations named after Node.js versions such as node_0.10 and node_0.12 are also present. The README is explicit that these exist for completeness and historical context and are not maintained.

The root package.json declares workspaces that map onto the same structure, listing globs such as src/1-getting-started/*/* and src/5-async-work/*/*. Each implementation subdirectory is therefore its own npm workspace with its own binding configuration, which is why the README instructs you to install and run inside the implementation directory rather than from the repository root.

Running a first example

The README gives a two-command recipe for any implementation subdirectory: install, then run the directory. There is no build step to invoke by hand, because the example's own package.json drives node-gyp through its install script.

Start by cloning the repository and moving into one implementation. The getting-started hello world example is the natural first stop:

cd src/1-getting-started/1_hello_world/node-addon-api
npm install
node ./

npm install resolves that subdirectory's dependencies and compiles the native binding. node ./ then executes the example's entry point, which loads the compiled addon and exercises it. What you see depends on the example; for a hello world it is a printed string returned from C++.

To run the whole set instead of one example, the root package.json defines a test script that drives test_all.js:

npm test

That script is the repository's own consistency check across the examples, and it is also the fastest way to find out whether your local toolchain can build every implementation on your machine.

If you are formatting C++ before contributing, the root defines a format script that runs clang-format over header and source files:

npm run format

Where the examples stop being useful

The examples are deliberately small. Each one demonstrates a single mechanism, which means none of them shows a realistic addon: there is no error-handling strategy spanning layers, no build configuration for multiple platforms, no packaging story for distributing a prebuilt binary. You will be writing all of that yourself, and the repository will not warn you when you get it wrong.

The maintenance boundary is the sharper limitation. The README states that implementations against unsupported Node.js versions are provided for completeness and historical context and are not maintained, and that the examples are primarily maintained for Node-API and node-addon-api. If you copy a nan example, you are copying from an API the README frames as the older approach; the Node.js addon documentation it links to advises using Node-API unless you need direct access to functionality Node-API does not expose.

A third constraint is toolchain weight. Every implementation compiles native code with node-gyp, so a working C++ toolchain is a prerequisite before any example runs. On a machine without one, npm install fails inside the example and the repository offers no fallback.

nan compared with Node-API and node-addon-api

The real alternative to this repository's Node-API examples is its own nan examples, and the difference is structural rather than cosmetic. nan sits between your C++ and V8's changing APIs, absorbing version differences at compile time. Node-API instead exposes a C surface whose ABI is stable across Node.js versions and JavaScript engines, so a binary built against it does not need recompiling when Node.js changes. node-addon-api wraps that C surface in C++ classes to reduce the boilerplate.

The practical consequence is visible in the directory listing: a nan implementation and a napi implementation of the same example sit next to each other, and you can read the two source files to see how much code the abstraction costs or saves. The README's guidance is unambiguous about which to prefer, pointing to the Node.js documentation's advice to use Node-API unless direct access to unexposed functionality is required.

If you want a different kind of alternative, the Node-API Resource site linked from the README is the tutorial-shaped counterpart to this example-shaped repository. It teaches the same APIs in sequence rather than presenting parallel implementations.

Maintenance, licensing and what to check before copying

The repository is not archived, and the last push was on 2026-07-13. That is recent enough that the Node-API and node-addon-api examples reflect current practice, but it says nothing about the nan and version-named implementations, which the README separates out as unmaintained historical material. Treat the tree as two tiers with different freshness.

There are no releases. Nothing is published from this repository, so there is no upgrade path to track and no version pin to bump. Your cost of adoption is the cost of reading and adapting source, plus the cost of keeping your adapted copy in step with Node.js yourself.

On licensing, the repository metadata reports a NOASSERTION licence identifier, meaning the platform could not classify it automatically. The repository does carry a LICENSE.md file at its root, so the terms are stated there rather than in machine-readable metadata. Read LICENSE.md and the attribution expectations in CONTRIBUTING.md before you copy example code into a product; that is a factual check on the files, not legal advice.

Editorial conclusion

Use this repository if you are new to Node.js C++ addons and want to compare how nan, Node-API and node-addon-api express the same task, or if you need a working reference for a specific topic such as async work or threadsafe functions. Do not treat it as a dependency: there is no published package to install and no versioned release, so nothing here belongs in your own package.json. Before copying code, confirm which Node.js versions a given implementation targets, since the README states that implementations against unsupported Node.js versions are provided for historical context and are not maintained, and check the LICENSE.md file yourself because the repository metadata does not resolve to a standard licence identifier.

Frequently asked questions

Official sources

1. Issues
2. nodejs/node-addon-examples on GitHub
3. README