title: Uses for N-API

Perhaps the most popular use for N-API is making the capabilities of an existing C/C++ library available to JavaScript programmers. This permits you to leverage the investment you've already made in your existing code, making it available to a whole new population of JavaScript programmers and projects.

For many applications, the C/C++ code base is the reference implementation. N-API permits you to continue to refine and maintain your existing C/C++ code. Improvements to the C/C++ code are then easily transferred to the JavaScript users.

Some applications, like those built on [Electron](https://electronjs.org) or [NW.js](https://nwjs.io), can benefit from accessing system toolkits and APIs not currently available through Node. N-API facilities accessing these system resources.

For low-powered devices, it may make sense to code computationally intensive tasks in C or C++ and then make that code available to JavaScript using N-API. Although in many cases Node's JavaScript runtime engine will eventually compile the JavaScript down to binary, N-API offers the ability to compile the C/C++ code just once and have the binary available to Node right from the start.

title: What is N-API?

N-API is the technology that enables the development of Node native modules.

[N-API](https://nodejs.org/api/n-api.html#n_api_n_api) is a toolkit introduced in Node 8.0.0 that acts as an intermediary between C/C++ code and the Node JavaScript engine. It permits C/C++ code to access, create, and manipulate JavaScript objects as if they were created by JavaScript code. N-API is built into Node versions 8.0.0 and later and requires no further installation.

There is another Node toolkit that predates N-API, [Native Abstractions for Node.js (NAN)](https://github.com/nodejs/nan) that serves a similar purpose. NAN is implemented using direct calls to the [Chrome V8](https://developers.google.com/v8/) that Node has historically used as its JavaScript engine. The disadvantage of this approach is that the NAN layer itself, as well as code that relies on it, needs to be updated every time the V8 engine used by Node is updated.

N-API, on the other hand, abstracts out its API from the underlying JavaScript engine. This provides two immediate benefits. The first is that N-API guarantees that the API will always be backward compatible. This means that a module you create today will continue to run on all future versions of Node without the need for running `npm install` again. Since N-API is ABI-stable, your module will continue to run even without recompilation.

The second benefit is that your module will continue to run even if Node's underlying JavaScript engine is changed. For example, there is a lot of interest in incorporating [Microsoft's ChakraCore](https://github.com/Microsoft/ChakraCore) JavaScript engine [into Node](https://github.com/nodejs/node-chakracore). Modules built on N-API will run on the ChakraCore engine without modification. In fact, they'll run without recompilation.

An important adjunct to N-API, although not strictly a part of the main project, is the npm [`node-addon-api`](https://www.npmjs.com/package/node-addon-api) module. The purpose of this module is to raise the N-API API from the level of "C" up to "C++". For many users, the object model implemented by `node-addon-api` makes the effort of creating N-API modules much easier and enjoyable.

[CMake.js](https://github.com/cmake-js/cmake-js) is good build tool alternative to [node-gyp](node-gyp.html). CMake.js is based on the [CMake](https://cmake.org) tool which must be installed.

- Not widely adopted in the Node community.

Your `package.json` file needs to have a couple of entires for your native module to work with CMake.js.

[**package.json**](https://github.com/nodejs/node-addon-examples/blob/master/build_with_cmake/node-addon-api/package.json)

When building a native module based on N-API, it is important to declare the minimum N-API version against which your module is designed to work. For CMake.js, this is accomplished by adding a line like this to the `CMakeLists.txt` file:

Additional configuration values are required for N-API modules based on `node-addon-api`.

Here is a complete `CMakeLists.txt` file for an N-API native module built on `node-addon-api`:

[**CMakeLists.txt**](https://github.com/nodejs/node-addon-examples/blob/master/build_with_cmake/node-addon-api/CMakeLists.txt)

A couple of working [examples](https://github.com/nodejs/node-addon-examples/tree/master/build_with_cmake).

Historically, [node-gyp](https://github.com/nodejs/node-gyp) has been the build tool of choice for the Node ecosystem. The tool comes bundled with Node and is nearly universally used to build Node native modules. Most of the examples on this site use node-gyp to build the binaries.

node-gyp is based upon Google's [GYP](https://gyp.gsrc.io/) build tool. GYP, in turn, requires Python.

For developers who find the node-gyp build tool too constraining, [CMake.js](cmake-js.html) is a good alternative.

- Is nearly universally used by the Node community to build native modules.