node-addon-api: C++ Wrapper Classes for Node-API
Module for using Node-API from C++
At a glance
- What is it?
- node-addon-api is a header-only C++ layer over the C Node-API. It gives addon authors a C++ object model and exception semantics, but it tracks only active LTS Node.js releases and requires C++17.
- Who is it for?
- Adopt node-addon-api if you are writing a native addon in C++ and want Node-API's ABI stability without hand-rolling C error checks. Skip it if you need to support a Node.js line that has left active LTS, because the README states a new major drops that support every year, or if you are happy with plain C Node-API or a build system that cannot consume a gyp file.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 27 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 28, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What node-addon-api removes from the C Node-API workflow
Node-API is a C API. Every call returns a status code, every value is an opaque napi_value handle, and cleanup of handles and scopes is the caller's job. node-addon-api is a set of header-only C++ wrapper classes that sit over that API, so the README describes it as providing "a C++ object model and exception handling semantics with low overhead". The target reader is an addon author who already intends to write native code and wants the ABI stability of Node-API without writing the boilerplate by hand.
The ABI point matters more than the syntax. Because node-addon-api is based on Node-API, an addon built against a given Node-API version runs on any Node.js release that supports that version, so a rebuild per Node.js major is not required. That is the reason to pick this over the older V8-internal addon approach. The trade is that you are limited to what Node-API exposes; anything Node-API does not surface is not reachable through the wrapper.
How the wrapper classes and Node-API versions fit together
The repository is a header distribution. The top level holds napi.h, napi-inl.h and napi-inl.deprecated.h, plus gyp files (node_addon_api.gyp, node_api.gyp, common.gypi, except.gypi, noexcept.gypi) and index.js. There is no compiled artifact for the wrapper itself: the headers are included into your addon and compiled as part of it.
node-addon-api supports targeting different Node-API versions, which the README frames as the mechanism that lets an addon run on the Node.js versions supporting the targeted version. The README also recommends publishing a Node-API version badge so consumers can tell which Node.js majors are supported, and points to the Node-API support matrix for mapping versions to releases. The support model is narrower than the ABI story suggests: only active LTS Node.js versions are supported, and the README states that every year a new major drops the LTS line that has gone out of service. The oldest Node.js version supported by the current release is 22.x, and the minimum C++ standard follows the oldest supported Node.js line, which is why the current version requires C++17 or later.
Installing node-addon-api and building a first addon
The README does not contain a step-by-step tutorial, and it does not list install commands. What can be confirmed is narrower: the package is published to npm under the name node-addon-api, which is the name used in the npm badge and in the repository's package.json, and the top level of the repository ships gyp files (node_addon_api.gyp, node_api.gyp, common.gypi, except.gypi, noexcept.gypi) alongside napi.h and napi-inl.h. The README points readers to doc/README.md for API references and to CHANGELOG.md for the changelog.
Because no install or build command appears in the README, there is no command here to copy. The only concrete facts about getting it are the package name on npm and the presence of the gyp files in the repository. Treat doc/README.md as the place to look for the API surface, and note that the current version is stated in the README as 8.9.2.
The LTS support window is the real constraint
The most consequential limitation is not performance or API coverage. It is the support policy. node-addon-api supports only active LTS Node.js versions, and the README is explicit that a new major drops the LTS version that has gone out of service each year. An addon that must keep working on an older Node.js line will eventually be pinned to an older node-addon-api major, and the README does not describe a long-term support branch for those older majors.
The C++ standard requirement compounds this. Because the minimum standard follows the oldest supported Node.js release line, the current version needs C++17 or later. A project stuck on an older toolchain, or on a compiler that does not offer C++17, cannot simply take the latest headers. The README also does not document rollback or downgrade procedures, so the practical answer is to pin the node-addon-api version in package.json and move deliberately. If your addon must run on Node.js versions outside active LTS, plain C Node-API or a different binding layer is the better fit.
node-addon-api compared with writing Node-API in C
The closest alternative is the C Node-API directly, without the wrapper. The difference is where the error handling lives. In C you check the napi_status returned by each call and unwind manually. node-addon-api replaces that with C++ exception semantics and an object model, which is what the README means by "exception handling semantics". The cost is a C++ toolchain and a C++17 baseline; the C API has no such requirement.
A second point of comparison is the older V8-internal addon style. That approach gives access to internals Node-API does not expose, but it does not carry the ABI stability guarantee that comes from building on Node-API. Choosing node-addon-api is choosing the stable, narrower surface. The repository also contains a benchmark/ directory and a unit-test/ directory, which indicates the project measures and tests its own wrapper behaviour, though the README does not publish benchmark numbers.
Release cadence, licence and upgrade cost
Releases are frequent and versioned with release-please: the repository carries release-please-config.json and .release-please-manifest.json, and the README states the current version as 8.9.2. The most recent releases listed are v8.9.2 on 2026-08-12, v8.9.1 on 2026-07-31 and v8.9.0 on 2026-06-26. The last push to the default branch was on 2026-09-02. The README directs readers to CHANGELOG.md for the complete changelog, and that file is the place to check before upgrading, since the README itself does not summarise breaking changes between majors.
Upgrade cost is driven by the annual LTS drop rather than by header churn. The licence is MIT, stated in the README and shipped as LICENSE.md, which permits use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence and does not impose copyleft obligations on your addon, but the exact wording in LICENSE.md is what governs, and this is not legal advice.
Editorial conclusion
Adopt node-addon-api if you are writing a native addon in C++ and want Node-API's ABI stability without hand-rolling C error checks. Skip it if you need to support a Node.js line that has left active LTS, because the README states a new major drops that support every year, or if you are happy with plain C Node-API or a build system that cannot consume a gyp file. Before committing, verify that your target Node.js major provides the Node-API version you intend to use, using the Node-API support matrix linked from the README, and confirm your toolchain compiles at C++17 or later.
Frequently asked questions
How do I install node-addon-api?
The package is published to npm under the name node-addon-api. The README does not list install commands, so the package name on npm and the gyp files in the repository are the concrete facts available.
What is node-addon-api?
It is a set of header-only C++ wrapper classes that simplify using the C Node-API provided by Node.js. The README describes it as providing a C++ object model and exception handling semantics with low overhead.
Which Node.js versions does node-addon-api support?
The support model covers only active LTS Node.js versions, and a new major drops the LTS line that has gone out of service each year. The README states the oldest Node.js version supported by the current release is 22.x.
Does node-addon-api require a specific C++ standard?
Yes. The minimum supported C++ standard follows that of the oldest supported Node.js release line, and the README states the current version therefore requires C++17 or later.
What licence does node-addon-api use?
It is licensed under MIT, as stated in the README and shipped as LICENSE.md in the repository.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nodejs-node-addon-api)
Community notes