# Node.js C++ Addons

* [Why create a node addon?](#why-create-a-node-addon)
* [How is a Node addon different than a C++ project?](#how-is-a-node-addon-different-than-a-c-project)
* [Native Abstractions for Node.js (NAN)](#native-abstractions-for-nodejs-nan)
* [Examples](#examples)
* [Developing addons](#developing-addons)
* [Where do I include other C++ libraries?](#where-do-i-include-other-c-libraries)
* [Versioning](#versioning)
* [Additional Resources](#additional-resources)

The following document outlines Mapbox's general approach to writing C++ modules for [Node.js](https://github.com/mapbox/cpp/blob/master/glossary.md#node) (often referred to as _addons_), and the _why_. Check out [node-cpp-skel](https://github.com/mapbox/node-cpp-skel), a skeleton library for creating a Node.js addon, to learn more about _how_ to create an addon. When we hit bottlenecks in JS/Node.js scripts that can be solved by high concurrency we will consider porting node modules to C++ to leverage the threadpool - https://www.joyent.com/blog/node-js-on-the-road-dc-young-hahn

Node is integral to the Mapbox APIs. Sometimes at scale, though, Node becomes a bottleneck for performance. Node is single-threaded, which blocks execution. C++ on the other hand allows you to execute operations without clogging up the event loop (learn more about the node event loop [here](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/)). Passing heavy operations into C++ and subsequently into C++ workers can greatly improve the overall runtime of the code.

### Why create a node addon?

1. To port a C++ project to Node to expose a new interface for the tool (like Mapnik & Node Mapnik)
1. Improve performance at scale where Node becomes the bottleneck (i.e. concurrency)

**Concurrency**

Concurrency is the process of executing different pieces of the same process to allow for parallel execution of these pieces [[wikipedia](https://en.wikipedia.org/wiki/Concurrency_(computer_science))]. Node.js addons allow us to take advantage of concurrent operations within our node applications by reaching into more than just the [v8](https://github.com/mapbox/cpp/blob/master/glossary.md#v8) thread, but this can result in a few surprises. In the example below, weve passed data from our node application, into the v8 thread, and subsequently into our worker threadpool. Here there are multiple workers executing code at the same time. In our worker, we have the following line:

```
std::cout