Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



Node.js API (N-API)

Version published
Install size
493 kB

Package description

What is node-addon-api?

The node-addon-api package is a helper library for building Node.js Addons in C++. It provides a C++ API that abstracts away the complexities of working with the low-level V8 and N-API provided by Node.js, making it easier to develop native addons.

What are node-addon-api's main functionalities?

Object Wrapping

Object wrapping allows C++ classes to be represented as JavaScript objects. It provides an easy way to create and manage objects that have a one-to-one relationship with C++ objects.

Napi::ObjectReference MyClass::constructor;

MyClass::MyClass(const Napi::CallbackInfo& info) : Napi::ObjectWrap<MyClass>(info) {
  // constructor implementation

Napi::Object MyClass::Init(Napi::Env env, Napi::Object exports) {
  Napi::HandleScope scope(env);

  Napi::Function func = DefineClass(env, "MyClass", {
    InstanceMethod("myMethod", &MyClass::MyMethod)

  constructor = Napi::Persistent(func);

  exports.Set("MyClass", func);
  return exports;

Function Arguments

The package provides a way to handle function arguments passed from JavaScript to C++ with type checking and conversion utilities.

Napi::Value MyFunction(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();
  if (info.Length() < 2) {
    Napi::TypeError::New(env, "Expected at least two arguments").ThrowAsJavaScriptException();

  Napi::String arg0 = info[0].As<Napi::String>();
  double arg1 = info[1].As<Napi::Number>().DoubleValue();

  // function implementation

  return Napi::String::New(env, "result");

Asynchronous Operations

node-addon-api provides utilities for performing asynchronous operations, allowing long-running tasks to be executed without blocking the Node.js event loop.

class MyAsyncWorker : public Napi::AsyncWorker {
  MyAsyncWorker(Napi::Function& callback) : AsyncWorker(callback) {}

  void Execute() override {
    // Do work in another thread

  void OnOK() override {
    Napi::HandleScope scope(Env());
    Callback().Call({Env().Null(), Napi::String::New(Env(), "Success")});

Napi::Value RunAsyncWork(const Napi::CallbackInfo& info) {
  Napi::Function callback = info[0].As<Napi::Function>();
  MyAsyncWorker* worker = new MyAsyncWorker(callback);
  return info.Env().Undefined();

Other packages similar to node-addon-api



2018-05-08 Version 1.3.0, @mhdawson

Notable changes:

  • Added documentation for Scopes
  • Added documentation for migration from NAN
  • Update documentation to better explain the use of NODE_ADDON_API
  • Implement data manipulation methods for dataview
  • Use built-in N-API on Node.js >= 6.14.2
  • Value
    • Added IsExternal()
    • IsObject() allow functions
  • String
    • Fixed initialization of std::string to nullptr
  • Fix test failures on linuxOne and AIX
  • Added basic tests for Scopes
  • Fix MSVC warning C4244 in tests


  • [386c2aeb74] - test: remove dep on later C++ feature (Michael Dawson)
  • [10697734da] - Use built-in N-API on Node.js >= 6.14.2 (Gabriel Schulhof)
  • [75086da273] - test: add basic tests and doc for scopes (Michael Dawson)
  • [341dbd25d5] - doc: update blurb explaining NODE_ADDON_API (Gabriel Schulhof)
  • [cf6c93e4ee] - don't try to escape null (Michael Dawson)
  • [15e4b35fc2] - test: fix MSVC warning C4244 in tests (Kyle Farnung)
  • [7f3ca03b8e] - Create a doc for migration (Sampson Gao)
  • [0a2177debe] - Fix test failures on linuxOne and AIX (Jinho Bang)
  • [d567f4b6b5] - Added Napi::Value::IsExternal() (Eric Bickle)
  • [1b0f0e004a] - Update (Michele Campus)
  • [faf19c4f7a] - Fixed initialization of std::string to nullptr (Eric Bickle)
  • [9c4d321b57] - Implement data manipulation methods for dataview (Jinho Bang)
  • [5a39fdca6f] - n-api: throw RangeError napi_create_typedarray() (Jinho Bang)
  • [1376377202] - Make IsObject() allow functions (Jinho Bang)
  • [673b59d319] - src: Initial implementation of DataView class (Jinho Bang)
  • [0a899bf1c5] - doc: update indication of latest version (Michael Dawson)
  • [17c74e5a5e] - n-api: RangeError in napi_create_dataview() (Jinho Bang)
  • [4058a29989] - n-api: fix memory leak in napi_async_destroy() (Jinho Bang)



Node.js API (N-API) Package

This package contains header-only C++ wrapper classes for the ABI-stable Node.js API also known as N-API, providing C++ object model and exception handling semantics with low overhead. It guarantees backward compatibility when used with older versions of Node.js that do not have N-API built-in.

N-API is an API for building native addons. It is independent from the underlying JavaScript runtime (e.g. V8 or ChakraCore) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions and flavors of Node.js. It is intended to insulate native addons from changes in the underlying JavaScript engine and allow modules compiled for one version to run on later versions of Node.js without recompilation. N-API guarantees the API and ABI compatibility across different versions of Node.js. So if you switched to a different version of Node.js, you would not need to reinstall or recompile the native addon.

APIs exposed by N-API are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA262 Language Specification.

  • Setup
  • API Documentation
  • Examples
  • Tests
  • More resource and info about native Addons
  • Code of Conduct
  • Contributors
  • License

Current version: 1.3

(See for complete Changelog)



API Documentation


Are you new to N-API? Take a look at our examples


To run the N-API tests do:

npm install
npm test

Take a look and get inspired by our test suite

More resource and info about native Addons

WG Members / Collaborators

NameGitHub link
Anna Henningsenaddaleax
Arunesh Chandraaruneshchandra
Benjamin Byholmkkoopa
Gabriel Schulhofgabrielschulhof
Hitesh Kanwathirthadigitalinfinity
Jason Ginchereaujasongin
Michael Dawsonmhdawson
Nicola Del GobboNickNaso
Sampson Gaosampsongao
Taylor Wollboingoing

Licensed under MIT


Last updated on 08 May 2018

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc