Node JS addons - NAN vs N-API?

Question

I am looking to working on a project using node js addons with C++. I came across two abstract library NAN and N-API that I can use. However I am unable to decide which one I should use. I was not able to find proper comparison between these two libraries.

What are the pros, cons and differences of both? How to choose between them?

So far I have found that NAN has more online tutorials/articles regarding async calls. But N-API is officially supported by Node (and was created after NAN as a better alternative, although not sure.)

Answer 1

My understanding is this:

The Node-API (formerly N-API) was added to the core node.js interface in v8.0.0. "It is intended to insulate Addons from changes in the underlying JavaScript engine…" to quote the documentation. It also provides some other wrappers around things like buffers and asynchronous work (which should help avoid some of the underlying non-stable APIs noted in their Implications of ABI stability section).

nan (Native Abstractions for Node) is indeed older and so also supports older versions of node.js — back to node.js 0.8! Now despite its author claiming back in 2017:

As I mentioned somewhere else, N-API is not meant to be directly used for anything. Where has this notion come from? It is an (effectively internal) low-level infrastructure layer meant to offer ABI stability. There will be another layer on top.

…I do not see much warning to that effect in the official Node.js add-on documentation. Perhaps this other comment is a bit more insightful:

Yes, you should still use NAN for production use. It covers every relevant version of Node.js. Also note that N-API is not intended for end users. You should eventually use https://github.com/nodejs/node-addon-api.

Again, that was in June of 2017 by the maintainer of nan at the time. It seems that node-addon-api has matured in the meantime and remains active. In fact, I found a comment in the -addon-api repo that is only a month old at present:

…part of the goal was to make it easy to transition from nan.

So I think the answer is:

• use nan if you want something mature and very backwards-compatible
• use node-addon-api if you want something forwards-looking in C++
• use Node-API/N-API if you are comfortable working in C and dealing with possible lower-level concerns

Answer 2

You should use the node-addon-API module for new C++ code (or N-API for C code). All supported (non-EOL) versions of Node.js support it, and it makes maintaining and distributing native add-ons much easier: whereas addons using NAN require rebuilding the module for each NODE_MODULE_VERSION (major version of Node.js), modules using N-API/Node-Addon-API are forward-compatible:

A given version n of N-API will be available in the major version of Node.js in which it was published, and in all subsequent versions of Node.js, including subsequent major versions.

There's a somewhat confusing compatibility matrix here. N-API version 3 is compatible with Node.js v8.11.2+, v9.11.0+ and all later major versions (v10+), for example.

On top of that, node-addon-API fixes a lot of the annoying parts of NAN (like Buffers always being char* instead of, say uint8_t*).

node-addon-API/N-API addons are compatible with the Bun and Deno runtimes as well.

---

NAN still works of course, and there are more learning resources online, but node-addon-API is the way forward.