Wrap C/C++ into Node.js: A Complete Tutorial for 2026

Integrating C/C++ code with Node.js allows you to leverage the performance of C/C++ with the flexibility of JavaScript. This tutorial will guide you through the process of wrapping a C++ file so that it can be used within a Node.js application. Whether you're aiming to optimize performance for computationally intensive tasks or reuse existing C++ libraries, this guide will help you bridge the gap between these two powerful languages.

Key Takeaways

• Understand the basics of Node.js and C++ integration using Node-API.
• Learn how to compile C++ code to a Node.js compatible add-on.
• Explore ffi-napi library for calling C/C++ functions from Node.js.
• Gain insights into common errors and how to troubleshoot them.
• Implement a working example of a Node.js application using C++ code.

With the ever-growing demand for performance and efficiency, combining C++ with Node.js is an excellent way to create high-performance applications. This tutorial will walk you through each step of the integration process, ensuring you have the knowledge needed to tackle real-world problems.

Prerequisites

• Basic understanding of C++ and Node.js.
• Node.js (v18 or later) and npm installed on your machine.
• Basic familiarity with a C++ compiler (e.g., GCC or Clang).
• Node-addon-api and ffi-napi libraries.

Step 1: Set Up Your Development Environment

First, ensure that you have Node.js and npm installed. You can download them from the official Node.js website. Verify your installation by running:

node -v
npm -v

Next, install a C++ compiler. For Windows, you might use MinGW, while Linux and macOS have GCC or Clang available by default. Check your C++ compiler version:

g++ --version

Install the Node-addon-api package, which provides C++ abstractions for Node.js add-ons:

npm install node-addon-api

Step 2: Write a Simple C++ Function

Create a C++ file named example.cpp with a simple function that adds two integers:

#include <napi.h>

Napi::Number Add(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();
  int a = info[0].As<Napi::Number>().Int32Value();
  int b = info[1].As<Napi::Number>().Int32Value();
  return Napi::Number::New(env, a + b);
}

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(example, Init)

Step 3: Configure the Build Process

Create a binding.gyp file to define the build configuration for your Node.js add-on:

{
  "targets": [
    {
      "target_name": "example",
      "sources": [ "example.cpp" ]
    }
  ]
}

The binding.gyp file tells the node-gyp tool how to build your add-on.

Step 4: Build the Add-on

Initialize a Node.js project if you haven't already:

npm init -y

Then, build your C++ add-on using node-gyp:

npx node-gyp configure build

This will compile your C++ code into a Node.js add-on, resulting in a .node file in the build directory.

Step 5: Use the C++ Function in Node.js

Create a test.js file to use the compiled Node.js add-on:

const example = require('./build/Release/example');
console.log('Result:', example.add(5, 10));

Run the Node.js script to test your setup:

node test.js

You should see the output Result: 15, demonstrating successful integration.

Common Errors/Troubleshooting

Here are some common issues you might encounter:

• Missing headers: Ensure Node-addon-api is installed and included correctly.
• Build errors: Verify your binding.gyp configuration and compiler setup.
• Runtime errors: Check that your Node.js project paths are correct and the add-on is properly required.

Conclusion

By following this tutorial, you have learned how to wrap a C++ file into Node.js, allowing you to call C++ functions from a JavaScript environment. This powerful combination can significantly enhance your application's performance and capability.

Frequently Asked Questions

What is Node-addon-api?

Node-addon-api is a C++ header-only library which simplifies the creation of Node.js add-ons by providing a C++ wrapper around Node-API.

Why use C++ with Node.js?

Combining C++ with Node.js allows you to leverage C++'s performance benefits within a high-level, asynchronous JavaScript environment.

How do I troubleshoot build errors?

Ensure that your C++ compiler and Node-gyp configurations are correct, and all necessary headers and libraries are included.