An introduction to C++ addons in Node.js

  • Node.js
  • Gabriele Romanato

Node.js is a JavaScript runtime platform based on Google's V8 engine, designed for building high-performance networking applications. One of the strengths of Node.js is its ability to extend its functionalities via C++ addons, allowing developers to create native modules that can interact directly with the operating system and other C/C++ libraries.

C++ addons offer several advantages:

  1. Performance: C++ addons can be much faster than pure JavaScript, especially for computationally intensive operations.
  2. Access to existing libraries: Many low-level libraries are written in C or C++, and addons allow you to use these libraries directly in Node.js.
  3. Interaction with hardware: To directly access hardware or specific system APIs, using C++ may be necessary.

Before starting with our C++ addon development, make sure you have installed on your system the following software:

  • Node.js
  • Python (for node-gyp)
  • A C++ compiler (for example, GCC on Linux, Xcode on macOS, or Visual Studio on Windows)
  • node-gyp, a native addon building tool

You can install node-gyp globally using npm:


npm install -g node-gyp

Here's how to create a simple C++ addon that exposes a function to add two numbers.

Create a directory for your project and initialize a new Node.js project:


mkdir my-addon
cd my-addon
npm init -y

Create a src folder and add the addon.cc file to it:


mkdir src
touch src/addon.cc

Write the following code in the addon.cc file:


#include <napi.h>

Napi::Number Add(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();
    if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsNumber()) {
        Napi::TypeError::New(env, "Number expected").ThrowAsJavaScriptException();
        return Napi::Number::New(env, 0);
    }

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

    return Napi::Number::New(env, sum);
}

Napi::Object Init(Napi::Env env, Napi::Object exports) {
    exports.Set(Napi::String::New(env, "add"), Napi::Function::New(env, Add));
    return exports;
}

NODE_API_MODULE(addon, Init)

Let's create a binding.gyp file in the root of the project with the following content:


{
    "targets": [{
       "target_name": "addon",
        "sources": [ "src/addon.cc" ]
     }]
}

Let's use node-gyp to compile the C++ code:


node-gyp configure
node-gyp build

This will generate a binary file in the build/Release directory called addon.node.

To use the addon, create a index.js file in the root of the project and add the following code:


const addon = require('./build/Release/addon');

console.log(addon.add(3, 5)); // Output: 8

Conclusion

C++ addons for Node.js are powerful tools that allow you to extend the functionality of your Node.js applications with improved performance and access to low-level libraries. While they require an understanding of C++ and memory management, tools like node-gyp and the N-API module make the development process more accessible.

Back to top