Welcome! This is a quick guide-sheet to get you started with Node.js C++ addons. It’s meant to be super-easy to skim and copy/paste into your code.
If you are looking for more explanation and depth, checkout the blog, my book, the full code demo.
Always create your addon in it’s own directory. If it’s going to be reusable, move the directory outside of your main project directory.
Each reusable addon needs (1) a package.json, (2) a binding.gyp, and (3) C++ source code. If your addon isn’t reusable, and isn’t a standalone module, then you can omit package.json
It’s almost always easier to set up your addon as an independent module. When done this way, you can require it from your local project, and a standard npm install will handle the entire build process.
Three key things happen in package.json:
Set gypfile totrue so npm install builds the addon automatically.
Set the entry point to the executable (“my_addon” below will be whatever you name your addon).
Add NAN as dependency (optional, but highly recommended!)
The binding file is where you define your build. If you only have one C++ file, and it’s platform independent (doesn’t use OS calls), then this is really straightforward. Make sure you use the right name for your addon - what you put for “my_addon” needs to match what you put in package.json, and in the C++ code below).
If you have platform specific source, you can add them with conditionals. In addition, if you have compiler flags they can be added as well. Check out my intro blog post on this for a bit more depth.
If you are feeling adventurous, check out the gyp documentation for all the options and use cases - however there is some chromium-only information there, so beware.
Integer data is similar. You can also do some error checking so undefined can be returned (or something else) instead of just NaN.
You’d need to load PassInteger the same way as PassNumber was added to the module.
String data uses a slightly different syntax…
Strings are pretty loosely interpreted. If you remove the info->IsString() check in the C++
and pass in undefined, you’ll get denifednu back!
Objects are a little more complicated. Here, pass object accepts an object with two properties, X and Y. It returns a new object with the sum and product. Most of the code is really dedicated to creating the necessary strings to serve as property names.
What else should you know?
There are bunch more topics that you’ll need to learn before really being able to take full advantage C++ from Node.js. Here are a few important topics, and some resources on this site for learning them.
Asynchronous addons methods: Most addon methods shouldn’t block the event loop when called, which means you should make them asynchronous - they will accept a callback which will be used to return the results of the call. You can start learning the asynchronous pattern here, and using NAN with async is covered here. You’ll also want to check out streaming data from C++ to Node.js, which extends the asynchronous model.
Using Buffer objects: You need to be mindful of copying data between V8 and C++ proper, you can incur some penalties you might not expect. In addition, memory management and multithreading (asynchronous addons) can be tricky. Check out my article on how not to share memory between async threads, and learn about using buffers to side step this issue and save yourself a lot of memory copying.
Deploying addons: You can publish addons to the npm registry just like any other module, but when you do this it means the C++ code in your addon needs to be built on the target machine, using a C++ compiler. If that’s an issue, check out using node-pre-gyp to publish and distribute binaries for your supported platforms. While your at it, check out deploying your addons to Amazon Lambda too!
Looking for more?
Sign up to for Node Addons newsletter so you find out when new articles are published right away. With your signup, you'll get a free copy of Chapter 2 - Understanding V8 Programming from the Node and C++ Integration e-book