NOTE: The default branch has been renamed! master is now named main
If you have a local clone, you can update it by running:
git branch -m master main git fetch origin git branch -u origin/main main
This module contains header-only C++ wrapper classes which simplify the use of the C based Node-API provided by Node.js when using C++. It provides a C++ object model and exception handling semantics with low overhead.
There are three options for implementing addons: Node-API, nan, or direct use of internal V8, libuv, and Node.js libraries. Unless there is a need for direct access to functionality that is not exposed by Node-API as outlined in C/C++ addons in Node.js core, use Node-API. Refer to C/C++ addons with Node-API for more information on Node-API.
node-addon-api module, which is not part of Node.js, preserves the benefits
of the Node-API as it consists only of inline code that depends only on the stable API
provided by Node-API. As such, modules built against one version of Node.js
using node-addon-api should run without having to be rebuilt with newer versions
It is important to remember that other Node.js interfaces such as
libuv (included in a project via
#include <uv.h>) are not ABI-stable across
Node.js major versions. Thus, an addon must use Node-API and/or
exclusively and build against a version of Node.js that includes an
implementation of Node-API (meaning an active LTS version of Node.js) in
order to benefit from ABI stability across Node.js major versions. Node.js
provides an ABI stability guide containing a detailed explanation of ABI
stability in general, and the Node-API ABI stability guarantee in particular.
As new APIs are added to Node-API, node-addon-api must be updated to provide wrappers for those new APIs. For this reason, node-addon-api provides methods that allow callers to obtain the underlying Node-API handles so direct calls to Node-API and the use of the objects/methods provided by node-addon-api can be used together. For example, in order to be able to use an API for which the node-addon-api does not yet provide a wrapper.
The Node-API Resource offers an excellent orientation and tips for developers just getting started with Node-API and node-addon-api.
- API Documentation
- More resource and info about native Addons
- Code of Conduct
Current version: 7.0.0
(See CHANGELOG.md for complete Changelog)
node-addon-api is based on Node-API and supports using different Node-API versions. This allows addons built with it to run with Node.js versions which support the targeted Node-API version. However the node-addon-api support model is to support only the active LTS Node.js versions. This means that every year there will be a new major which drops support for the Node.js LTS version which has gone out of service.
The oldest Node.js version supported by the current version of node-addon-api is Node.js 16.x.
The following is the documentation for node-addon-api.
- Full Class Hierarchy
- Addon Structure
- Data Types:
- Error Handling
- Object Lifetime Management
- Memory Management
- Async Operations
- Thread-safe Functions
- Version management
Are you new to node-addon-api? Take a look at our examples
- Hello World
- Pass arguments to a function
- Object factory
- Function factory
- Wrapping C++ Object
- Factory of wrapped object
- Passing wrapped object around
To run the node-addon-api tests do:
npm install npm test
To avoid testing the deprecated portions of the API run
npm install npm test --disable-deprecated
To run the tests targeting a specific version of Node-API run
npm install export NAPI_VERSION=X npm test --NAPI_VERSION=X
where X is the version of Node-API you want to target.
To run a specific unit test, filter conditions are available
Example: compile and run only tests on objectwrap.cc and objectwrap.js
npm run unit --filter=objectwrap
Multiple unit tests cane be selected with wildcards
Example: compile and run all test files ending with "reference" -> function_reference.cc, object_reference.cc, reference.cc
npm run unit --filter=*reference
Multiple filter conditions can be joined to broaden the test selection
Example: compile and run all tests under folders threadsafe_function and typed_threadsafe_function and also the objectwrap.cc file npm run unit --filter='*function objectwrap'
To run the node-addon-api tests with
npm run-script dev
If you want a faster build, you might use the following option:
npm run-script dev:incremental
Take a look and get inspired by our test suite
You can run the available benchmarks using the following command:
npm run-script benchmark
See benchmark/README.md for more details about running and adding benchmarks.
More resource and info about native Addons
- C++ Addons
- Node-API - Next Generation Node API for Native Modules
As node-addon-api's core mission is to expose the plain C Node-API as C++
wrappers, tools that facilitate n-api/node-addon-api providing more
convenient patterns for developing a Node.js add-on with n-api/node-addon-api
can be published to NPM as standalone packages. It is also recommended to tag
such packages with
node-addon-api to provide more visibility to the community.
Quick links to NPM searches: keywords:node-addon-api.
napi-rs - (
The use of badges is recommended to indicate the minimum version of Node-API required for the module. This helps to determine which Node.js major versions are supported. Addon maintainers can consult the Node-API support matrix to determine which Node.js versions provide a given Node-API version. The following badges are available:
We love contributions from the community to node-addon-api! See CONTRIBUTING.md for more details on our philosophy around extending this module.
|Nicola Del Gobbo||NickNaso|
Licensed under MIT