A skeleton for binding C++ libraries to Node.js using Nan. This is a small, helper repository that generates simple HelloWorld Javascript example constructors. The examples have a number of methods to demonstrate different ways to use Nan for building particular types of functionality (i.e. asynchronous functions). Use this repo as both a template for your own code as well as a learning tool if you're just starting to develop Node/C++ Addons.

Why port C++ to Node.js?. That's a great question! C++ is a high performance language that allows you to execute operations without clogging up the event loop. Node.js is single-threaded, which blocks execution. Even in highly optimized javascript code it may be impossible to improve performance. Passing heavy operations into C++ and subsequently into C++ workers can greatly improve the overall runtime of the code. Porting C++ code to Node.js is also referred to as creating an "Addon".

Nan: Nan is used in many C++ => Node.js port projects, such as node-mapnik, node-osrm, and node-osmium. More examples of how to port C++ libraries to node can be found at nodejs.org/api/addons.html. See https://nodesource.com/blog/c-add-ons-for-nodejs-v4/ for a detailed summary of the origins of Nan.

This repository itself can be cloned and edited to your needs. The skeleton prepares a C++ port to Node.js and provides the following for quick development:

• Tests: created with Tape in the test/ directory. Travis CI file is prepared to build and test your project on every push.
• Documentation: use this README as a template and customize for your own project. Also, this skeleton uses documentation.js to generate API documentation from JSDOC comments in the .cpp files. Docs are located in API.md.
• Benchmarking: Easily test the performance of your code using the built-in benchmark tests provided in this skeleton.
• Build system: node-pre-gyp generates binaries with the proper system architecture flags
• Publishing: Structured as a node module with a package.json that can be deployed to NPM's registry.
• Learning resources: Read the detailed inline comments within the example code to learn exactly what is happening behind the scenes. Also, check out the extended tour to learn more about Node/C++ Addon development, builds, Xcode, and more details about the configuration of this skeleton.

Each make command is specified in Makefile

git clone git@github.com:mapbox/node-cpp-skel.git
cd node-cpp-skel

# Build binaries. This looks to see if there were changes in the C++ code. This does not reinstall deps.
make

# Run tests
make test

# Cleans your current builds and removes potential cache
make clean

# Cleans everything, including the things you download from the network in order to compile (ex: npm packages).
# This is useful if you want to nuke everything and start from scratch.
# For example, it's super useful for making sure everything works for Travis, production, someone else's machine, etc
make distclean

# This skel uses documentation.js to auto-generate API docs.
# If you'd like to generate docs for your code, you'll need to install documentation.js,
# and then add your subdirectory to the docs command in package.json
npm install -g documentation
npm run docs

Note: by default the build errors on compiler warnings. To disable this do:

WERROR=false make

node-cpp-skel was designed to make adding custom code simple and scalable, to form to whatever usecase you may need. Here's how:

• Create a dir in ./src to hold your custom code. See the example code within /src for reference.
• Add your new method or class to ./src/module.cpp, and #include it at the top
• Add your new file-to-be-compiled to the list of target sources in ./binding.gyp

Code coverage is critical for knowing how well your tests actually test all your code. To see code coverage you can view current results online at or you can build in a customized way and display coverage locally like:

make coverage

For more details about what make coverage is doing under the hood see https://github.com/mapbox/cpp#code-coverage