Extending Node.js with native C++ modules
Beware — going low level might end up as if you wanted to pimp your ride in a custom car shop. Of course you might get this nitro boost, but things can get overdone quickly:
Hello, (native) world!
Enough warnings, now you’re ready for your first lines of C++ code that will be compiled into native node module.
.cpp file (I named it main.cpp) and fill it with following piece of code:
Note that the methods created in C++ are void, they don’t return any value explicitly. Instead you set the return value on the “bridge”
info object (reference of type
Nan::FunctionCallbackInfo, “implicitly” passed in a
In order to run the code, you still need to compile it. Fear not, you don’t have to call the C++ compiler manually. Node.js has got you covered.
For a good start, initialize Node.js project in the same directory where you have your
npm init -y
Next, install Nan and node-gyp (you know Nan already; node-gyp is a set of tools for native code compilation):
npm install nan node-gyp --save
package.json file so that it contains following lines (versions of your dependencies might slightly differ, but it’s totally fine!):
The important part here is the
"compile": “node-gyp rebuild”— for C++ code compilation
"start": "node main.js"— for our main executable script
Now, create a
bindings.gyp file — it’s a sort of configuration file for node-gyp. Note how it uses
"main.cpp” (your “hello world” source) filename in the array under
You will also need these three tools installed on your machine (you should be fine on macOS — they come preinstalled; they are also easy too install on Linux, eg Ubuntu with apt-get):
- python 2.7
If any of these is missing, node-gyp will report it, so don’t waste your time figuring out whether you have them on your OS or not.
It’s time for your first compilation —
npm run compile (remember, it will start node-gyp and compile your C++ sources as configured in
bindings.gyp file). If everything went smoothly, you should see similar output:
> email@example.com compile /Users/marcin/projects/node-native-addons-example
> node-gyp rebuildCXX(target) Release/obj.target/addon/main.o
That’s sweet, but how about something more useful?
Of course. You would like to see where the native modules really shine.
The algorithm will:
- first, check if the only argument is a number (if not — throw a
- second, check if the number is less than 2 (if so, return
- third, iterate in range of 2 up to a number (exclusively) and check whether the modulo operation yields zero (if so, break the loop & return
falsebecause such number is not prime);
trueat the very end — the number “made it” through the loop, so it must be prime.
(for simplicity, I deliberately omitted the checks against non-integers or negative numbers; I’ll leave it as an exercise for you!)
Now, for the
main.cpp file, replace it’s contents with following code (note that I removed the
Hello function here):
main.js file and swap the existing content with following code:
npm run compile to compile your C++ module and
npm start to execute the
The repo with complete example is available on my Github.
What would be your use case for developing Node.js modules with C++?