This module contains header-only C++ wrapper classes which simplify the use of the C based N-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: N-API, nan, or direct use of internal V8, libuv and Node.js libraries. Unless there is a need for direct access to functionality which is not exposed by N-API as outlined in C/C++ addons in Node.js core, use N-API. Refer to C/C++ addons with N-API for more information on N-API.
node-addon-api module, which is not part of Node.js, preserves the benefits
of the N-API as it consists only of inline code that depends only on the stable API
provided by N-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 N-API and/or
exclusively and build against a version of Node.js that includes an
implementation of N-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 N-API ABI stability guarantee in particular.
As new APIs are added to N-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 N-API handles so direct calls to N-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 N-API Resource offers an excellent orientation and tips for developers just getting started with N-API and node-addon-api.
- API Documentation
- More resource and info about native Addons
- Code of Conduct
Current version: 3.1.0
(See CHANGELOG.md for complete Changelog)
node-addon-api is based on N-API and supports using different N-API versions. This allows addons built with it to run with Node.js versions which support the targeted N-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 10.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 targetting a specific version of N-API run
npm install export NAPI_VERSION=X npm test --NAPI_VERSION=X
where X is the version of N-API you want to target.
To run the node-addon-api tests with
npm run-script dev
If you want 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
As node-addon-api's core mission is to expose the plain C N-API as C++
wrappers, tools that facilitate n-api/node-addon-api providing more
convenient patterns on developing a Node.js add-ons 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.
The use of badges is recommended to indicate the minimum version of N-API required for the module. This helps to determine which Node.js major versions are supported. Addon maintainers can consult the N-API support matrix to determine which Node.js versions provide a given N-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