🤖 Beginners guide to writing NodeJS Addons using C++ and N-API (node-addon-api)

Atul

Follow

Jun 15, 2018 · 9 min read

According to nodejs.org:

Node.js Addons are dynamically-linked shared objects, written in C++, that can be loaded into Node.js using the require() function, and used just as if they were an ordinary Node.js module. They are used primarily to provide an interface between JavaScript running in Node.js and C/C++ libraries.

There can be many reasons to write nodejs addons:
1. You may want to access some native apis that is difficult using JS alone.
2. You may want to integrate a third party library written in C/C++ and use it directly in NodeJs.
3. You may want to rewrite some of the modules in C++ for performance reasons.
Whatever your reason is, this blog focuses on explaining the N-API and how you can use it to build C/C++ based NodeJS addons.

The complete source code from this blog is available at
https://github.com/master-atul/blog-addons-example
So, If you are not interested in reading through, you can directly take a look at the code there also.

What is N-API ?

N-API (pronounced N as in the letter, followed by API) is an API for building native Addons. It is independent from the underlying JavaScript runtime (ex V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate 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.

In essence , N-API can be used to build NodeJS Addons using C or C++. And the addons built using this would not break across different implementations or versions of NodeJS.

N-API is a stable API as of Node v10 (latest stable release when writing this article). N-API was experimental in Node v8 and v9.

To see a demo of N-API in action watch this youtube video:

This article will only focus on C++ addons for NodeJs using N-API. For this we will use the node-addon-api (https://github.com/nodejs/node-addon-api) package from the N-API team which contains header-only C++ wrapper classes for the N-API ( basically it provides C++ object model and exception handling semantics with low overhead).

Since this blog post covers very minimal theory, I suggest you follow through by coding live as you read.

Lets Code: Boilerplate setup

Create a basic node project test-addon

mkdir test-addon
cd test-addon
git init
npm init

Install the dependencies:

npm install node-gyp --save-dev
npm install node-addon-api

node-gyp is the toolchain to compile the addons.
node-addon-api is a helper project as described earlier that will make writing C++ addons easier.

In the package.json set the attribute gypfile:true and setup the following files as below:

binding.gyp file contains all the files that need to be compiled and all the include files / libraries that the project will be using. If you notice we have added cppsrc/main.cpp file as our source file.

Also our package.json mentions a index.js file as its main file.
Lets create both of them :

The base boilerplate is complete. Lets try and build our addon

type npm run build

You should have an output similar to this:

npm run build> test-addon@1.0.0 build /Users/atulr/Projects/Hobby/test-addon
> node-gyp rebuildSOLINK_MODULE(target) Release/nothing.node
  CXX(target) Release/obj.target/testaddon/cppsrc/main.o
  SOLINK_MODULE(target) Release/testaddon.node

Wohoo ! compilation was successful. Lets run it !

Type node index.js . Sadly you will not get any output here.

Ideally you should use a debugger tool to debug and see what the contents of testAddon is but for demo here lets just add a console.log like this:

//index.jsconst testAddon = require('./build/Release/testaddon.node');
console.log('addon',testAddon);
module.exports = testAddon;

Now run index.js again. You should see an output like this :

node index.js
addon {}

Awesome !! Now we have a working setup to start with.

Before we go ahead, lets take a look at cppsrc/main.cpp in detail:
1. #include<napi.h> includes the napi header file so that we can access all the helper macros, classes and functions.
2. NODE_API_MODULE is a macro that accepts modulename and registerfunction as parameters.
3. In our case registerfunction is InitAll and it takes two parameters which are passed by N-API. First parameter env is the context that needs to be passed on to most N-API function and exports is the object used to set the exported functions and classes via N-API.

The source code documentation for NODE_API_MODULE says:

/**
* This code defines the entry-point for the Node addon, it tells Node where to go
* once the library has been loaded into active memory. The first argument must
* match the "target" in our *binding.gyp*. Using NODE_GYP_MODULE_NAME ensures
* that the argument will be correct, as long as the module is built with
* node-gyp (which is the usual way of building modules). The second argument
* points to the function to invoke. The function must not be namespaced.
*/
NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)

To read in more depth you can visit the documentation of node-gyp here:
https://github.com/nodejs/node-addon-api/blob/master/doc/node-gyp.md

Exporting a Hello World C++ function using N-API

Now lets add an example of exporting a C++ function to NodeJS.
Lets take an example of a simple function

std::string hello(){
  return "Hello World";
}

Lets try to export hello to Javascript side with our addon.
Create the following files:
cppsrc/Samples/functionexample.h

#include <napi.h>namespace functionexample {
  std::string hello();
  Napi::String HelloWrapped(const Napi::CallbackInfo& info);
  Napi::Object Init(Napi::Env env, Napi::Object exports);
}

The corresponding cppsrc/Samples/functionexample.cpp

#include "functionexample.h"std::string functionexample::hello(){
  return "Hello World";
}
Napi::String functionexample::HelloWrapped(const Napi::CallbackInfo& info) 
{
  Napi::Env env = info.Env();
  Napi::String returnValue = Napi::String::New(env, functionexample::hello());
  
  return returnValue;
}
Napi::Object functionexample::Init(Napi::Env env, Napi::Object exports) 
{
  exports.Set(
"hello", Napi::Function::New(env, functionexample::HelloWrapped)
  );
 
  return exports;
}

Wow ! Looks like a lot. But if you look closely, its not as complex as it looks. For every function in C++ we want to export we will basically create a NAPI wrapped function (HelloWrapped in this example) and add it to the exports object using Init.

Lets take some time to understand HelloWrapped function. Every wrapped function that needs to be exported to JS should have input params/return value from the Napi namespace.
Every wrapped function takes in CallbackInfo as the input parameter. This contains things like the context and the input parameters that needs to be passed to the function.

Initfunction is used to just set the export key as hello with corresponding wrapped function HelloWrapped .

Now we need to make our node-gyp know that we have added extra c++ files. So make the following changes to binding.gyp,main.cpp and index.js

Remember : Any change in c++ src files will need recompilation before you can use the changes in NodeJS.
So make sure you run npm run build again after changing c++ files.

Also when you add a new header file/cpp file :
1. Add it to binding.gyp
2. Add it to main.cpp
3. Do npm rebuild and access it via JS.

Now run it ! node index.js .You should see the output as follows:

node index.js
addon { hello: [Function] }
Hello World

Voila ! Now we have a hello world from C++ world into JS World!

How about functions with input parameters ?

Lets say that the function that we want to export has both input and output params. For example:

int add(int a, int b){
  return a + b;
}

To add the function we will make the following changes:

Explanation:
1. We added a simple add function.
2. We added the wrapper for the add function : AddWrapped which is used to interface the add function with N-API.
3. We added the key add to export the AddWrapped function to the JS.

I believe the example is fairly straightforward and self explanatory. If more explanation is needed, let me know in the comments and I ll add more details here. Passing complex references and objects to the functions will be covered in the later sections below.

Output:

node index.jsaddon { hello: [Function], add: [Function] }
hello  Hello World
add  15

Awesome !!

Exporting a Hello World C++ Class using N-API

Lets create a simple C++ class that stores a double value. The member functions are pretty self explanatory.

I believe the above code is pretty straightforward and self explanatory.
To export this class to JS side we will need to create a wrapper class. Lets name the wrapper class as ClassExample .

Create the wrapper Class as follows:
Please look at the classexample.h first and try to grasp the intent of the Wrapper class before going to the implementation.

Lets take a good look at the header file of our wrapper class classexample.h:

As mentioned before, Anything that needs to be exported to JS world needs to be wrapped with N-API. Hence:
1. First step is to create a wrapper class which extends Napi::ObjectWrap<ClassExample> .
2. Just like in case of functions we need a Init method to set the export key.
3. Except the static Napi::FunctionReference constructor; rest all the methods are self explanatory.

Now, lets take a look at the actual implementation classexample.cpp .
1. ClassExample::Init function is responsible to create and set the export key. Here we will export the class as ClassExample to the JS side.

Important part here is :

Napi::Function func = DefineClass(env, "ClassExample", 
{
  InstanceMethod("add", &ClassExample::Add),
  InstanceMethod("getValue", &ClassExample::GetValue),
});constructor = Napi::Persistent(func);

func is used to define the class that will be exported to JS and then the func is assigned to constructor which is a static function reference in c++. This is where the earlier defined static Napi::FunctionReference constructor; comes in. Similar to InstanceMethod there are various methods defined in NAPI to export different types of class methods. For example: Static methods can be exported using StaticMethod .

If you are wondering what env is :

env is the environment that represent an independent instance of the JavaScript runtime,

I think of it as the js context that needs to be passed around to most NAPI functions as the first argument.

2. Now lets see the implementation of ClassExample::Add function.

Napi::Value ClassExample::Add(const Napi::CallbackInfo& info) 
{
  Napi::Env env = info.Env();
  Napi::HandleScope scope(env);
  
  if (info.Length() != 1 || !info[0].IsNumber()) {
     Napi::TypeError::New(env, "Numberexpected").ThrowAsJavaScriptException();
  }  Napi::Number toAdd = info[0].As<Napi::Number>();
  double answer = this->actualClass_->add(toAdd.DoubleValue());
  return Napi::Number::New(info.Env(), answer);
}

Here input params are checked first using info from env. Now, to read a value from JS side we read it like info[0].As<Napi::Number>();. Since C++ is a strongly typed language and JS is not. We have to convert every value that we get from JS side to its appropriate type. After we convert the value we simply call the internal actualClass
instance and return the value. But since the value is a double we need to wrap it with a Napi::Number instance so that it can be passed to the JS side.

We are not done yet. Remember we need to now add entries to tell the compiler to compile the new source files we added.

Make the above changes and run npm run build , followed by node index.js .
Notice that we have to both classexample.cpp and actualclass.cpp in the binding.gyp . The reason is that both classes are written by us. If you have a thrid party library c++ file. Then you would need to include the precompiled dynamic library in the libraries section of binding.gyp instead.

Output:

node index.jsaddon { hello: [Function],
  add: [Function],
  ClassExample: [Function: ClassExample] }
hello  Hello World
add  15
Testing class initial value :  4.3
After adding 3.3 :  7.6

That was easy 😉 ! Isn’t it 😜 ?

This should be enough for most use cases. But if you need to know how to send class instances back/any complex object between JS and C++ read on.

Sending complex js objects to the C++ world

Lets say we have a use case like below:

const prevInstance = new testAddon.ClassExample(4.3);
console.log('Initial value : ', prevInstance.getValue());
console.log('After adding 3.3 : ', prevInstance.add(3.3));const newFromExisting = new testAddon.ClassExample(prevInstance);console.log('Testing class initial value for derived instance');
console.log(newFromExisting.getValue()); 

Here, we have an instance of ClassExample in prevInstance .
And we want a new instance newFromExisting which has same value of prevInstance. For that, we want to pass the existing instance prevInstance to the constructor of ClassExample . Since, prevInstance is not a primitive value like int, double etc. The expected output of the last console.log should be 7.6 .

Lets see how we can do that:

In the above changes.

1. First thing we did is change the implementation of ClassExample::ClassExample so that it can take an argument which is not a number.
2. Now we assume that if the argument is not a number, it must be an instance of the ClassExample itself. So to get the class instance from the JS side we need to UnWrap the object.

Napi::Object object_parent = info[0].As<Napi::Object>();ClassExample* example_parent = Napi::ObjectWrap<ClassExample>::Unwrap(object_parent);ActualClass* parent_actual_class_instance = example_parent->GetInternalInstance();this->actualClass_ = new ActualClass(parent_actual_class_instance->getValue());return;

So we Unwrap the object using the unwrap method and then to get to the actualClass instance of in the ClassExample we defined an additional method called GetInternalInstance which simply returns the internal actualClass reference. Finally, we take the value from actualClass instance and create new actualClass instance for the new ClassExample instance.

Lets again run it! npm run build and then node index.js

Output:

node index.jsInitial value :  4.3
After adding 3.3 :  7.6
Testing class initial value for derived instance
7.6

Crazy !! 🎉 We got the expected 7.6 Wohoo !! 🌮

The entire source code is available at : https://github.com/master-atul/blog-addons-example

I hope this helps someone trying to use N-API and create C++/C addons for NodeJS. 🌮🌮

More references :
- https://github.com/nodejs/abi-stable-node-addon-examples/
- https://github.com/nodejs/node-addon-api.git/
- https://nodejs.org/api/addons.html