NAN 2.28: The Header-Only Compatibility Layer for Node.js Native Addons
GitHub describes it as Native Abstractions for Node.js. The repository metadata lists C++ as its primary language. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README.
At a glance
- What is it?
- NAN is a C++ header library that abstracts V8 API changes across Node.js versions 8 through 26. It trades a learning curve for the ability to write one addon source that compiles across a decade of Node releases.
- Who is it for?
- Adopt NAN if you must support a wide range of Node.js versions (8 through 26) with a single C++ addon source and you are comfortable with a macro-heavy API that mirrors the old V8 style. Do not use it for new projects that can target modern Node.js versions only; N-API is the official, stable alternative and avoids the churn of V8 internals.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 28 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- nodejs/nan3,352 ★ · -1
| Repository | 2026-08-13 | 2026-11-15 |
|---|---|---|
| nodejs/nan | 3.4k | 3.4k |
-1 Stars in the last 94 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The Problem: V8 Churn and Addon Breakage
Node.js addons are compiled C++ shared objects that link against V8, the JavaScript engine. V8 changes its API frequently, and each Node.js major version can break existing addons at the source level. The README calls this a "minor nightmare," specifically citing the transitions from 0.10 to 0.12 to 4.0. Developers used to have to inspect NODE_MODULE_VERSION and write conditional preprocessor macros to handle each version's differences. NAN exists to eliminate that manual work. It is a single header file that wraps V8's API with its own macros and types, so the same C++ code compiles across Node.js versions 8, 10, 12, 14, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25 and 26. The target audience is anyone writing native addons, particularly those who must support a broad range of Node versions without maintaining multiple source branches.
How NAN Works: Macros, Handles, and Templates
NAN is not a runtime library. It is a set of C++ header files that provide macros and utility classes. The central idea is to abstract the parts of V8 that change between versions. For example, method signatures for JavaScript-accessible functions varied widely across V8 versions, including the now-removed v8::Argument type. NAN defines its own types like Nan::FunctionCallbackInfo and Nan::PropertyCallbackInfo that map to the correct V8 types on each version. Similarly, handle scopes are implemented as Nan::HandleScope and Nan::EscapableHandleScope, because the creation and deletion of HandleScope objects differs across V8 versions. Templates, which are blueprints for JavaScript functions and objects, are also wrapped. The API list shows Nan::SetMethod, Nan::SetPrototypeMethod, Nan::SetAccessor, and Nan::SetTemplate among others. The result is that you write code that looks like the most recent V8 API but that compiles against older versions without manual #ifdef chains. The README explicitly promises to avoid the "macro-tangle" that comes from inspecting NODE_MODULE_VERSION directly.
Installation and Build Integration
To use NAN, you install it as a dependency with npm, yarn, or bun. The README shows the command npm install nan. Then you add the path to NAN to your binding.gyp file so that the compiler can find nan.h. The exact snippet is: "include_dirs" : [ "<!(node -e \"require('nan')\")" ]. This is a shell command substitution that runs Node to print the directory where the nan package is installed. That directory is used as an include path, equivalent to -I<path-to-NAN> during compilation. This approach is simple but requires that node and the nan package are available in the build environment. The README also points to a boilerplate project, node-native-boilerplate, and a set of examples, including an async pi estimation example that uses Monte Carlo methods. The C++ test suite is described as comprehensive, with many code snippets you can copy. There is no mention of a build step beyond including the header; you still need a build system like node-gyp, but NAN itself does not require compilation.
The API Surface: More Than Just Method Declarations
NAN covers more than just function callbacks. The README lists a wide range of abstractions: property getters and setters, index getters and setters, enumerators, deleters, and query handlers. There are helpers for setting methods on prototypes, accessors, and templates. The scopes section covers handle scopes and escapable handle scopes. This is a broad API that mirrors the V8 embedding API but with a stable interface. The documentation is split into separate markdown files, such as doc/methods.md and doc/scopes.md, which are linked from the README. There is also a reference to the V8 Getting Started Guide and the Node Add-on Documentation. For a developer, this means you have to learn NAN's naming conventions instead of V8's. The trade-off is that you learn one API that works across many versions, rather than learning the differences between each version. The README claims that NAN's interface is "similar to the most recent V8 API," which helps if you are already familiar with modern V8, but the older versions used types like v8::Argument that no longer exist, so NAN acts as a translator.
Limitations and When NAN Is the Wrong Tool
NAN is not a silver bullet. The most obvious limitation is that it is a compatibility layer, not a stable ABI. It still compiles against V8 headers, which means each Node.js version may require a recompile of the addon. The README does not mention prebuilt binaries or ABI stability. Another limitation is the macro-heavy style. The README itself jokes about the "macro-tangle" that NAN avoids, but NAN introduces its own set of macros and types. If you are not familiar with them, the learning curve is steep. Also, NAN only supports the versions listed, and older versions like Node 0.10 are not covered by the current version. For new projects that target only modern Node.js (say 16 and above), NAN might be overkill. The official N-API (now called node-api) provides a stable ABI that does not require recompilation for each Node version. NAN is also a separate dependency that you must manage, and its API is not the same as V8's, so if you ever need to drop down to raw V8 calls, you have to translate. The README does not mention any performance overhead, but wrapping V8 calls in macros generally compiles to the same code, so that is not a concern. The real issue is maintenance: as V8 evolves, NAN must be updated, and you are at the mercy of the project's release schedule.
The Alternative: N-API and Its Different Approach
The main alternative to NAN is N-API, which the Node.js documentation promotes as the official addon API. N-API is a C API that is part of Node.js itself, and it is designed to be ABI-stable across Node versions. That means an addon compiled against N-API does not need to be recompiled when you upgrade Node.js, as long as the N-API version is compatible. NAN, by contrast, compiles against V8 headers and must be rebuilt for each Node version. The trade-off is that N-API is a lower-level C API, while NAN provides a C++ wrapper that is more convenient for many developers. N-API also has a C++ wrapper called node-addon-api, which is a separate project. The README for NAN does not mention N-API, but the Node Add-on Documentation link in the README likely covers it. If you are starting a new addon and can require a recent Node version, N-API is the safer choice because it reduces maintenance overhead. However, if you need to support Node 8 through 26 with a single source file and you are already comfortable with NAN's style, NAN remains a viable option. The choice comes down to whether you value ABI stability or source-level compatibility across a wider range of versions.
Maintenance, License, and the Cost of Upgrades
NAN is an open source project under the MIT license, which is permissive for commercial use. The current version is 2.28.0, and the repository has a CHANGELOG.md that tracks changes. The README does not provide a release cadence or a maintenance policy, but the project is under the Node.js organization, which suggests some level of governance. The README mentions governance and contributing sections. For a developer, the maintenance cost comes from two sides. First, you must keep up with NAN releases to support new Node.js versions. Each time Node.js adds a new major version, NAN may need an update to handle V8 changes. Second, your addon's build process must recompile against the new NAN headers. There is no prebuilt binary mechanism mentioned. The license is a positive factor: MIT means you can use it without copyleft obligations. However, the cost of upgrading is real. You should check the CHANGELOG before upgrading NAN, as the README points to it for a complete change log. The test suite is available, which can help verify that your addon still works after an upgrade, but the README does not describe how to run the tests.
A Concrete Example: The Async Pi Estimation
The README links to an example in the repository: a Monte Carlo pi estimation addon that runs asynchronously. This example is useful because it shows how NAN handles asynchronous work, which is a common need in native addons. The README says the example includes full code and an explanation. What we can infer is that it uses NAN's abstractions to create a JavaScript-accessible function that performs a computation off the main thread, then invokes a callback with the result. This pattern is typical for addons that do CPU-intensive work without blocking the event loop. For a developer evaluating NAN, this example is a good starting point. The README also mentions a newline detection example, nan-example-eol, which is a simpler illustration. The existence of these examples suggests that NAN is mature enough to have practical demonstrations. The C++ test suite is described as comprehensive, which gives some confidence in correctness, but again, no test results are shown.
Editorial conclusion
Adopt NAN if you must support a wide range of Node.js versions (8 through 26) with a single C++ addon source and you are comfortable with a macro-heavy API that mirrors the old V8 style. Do not use it for new projects that can target modern Node.js versions only; N-API is the official, stable alternative and avoids the churn of V8 internals. Before adopting, verify the specific NAN macros you rely on are still present in 2.28.0 and check the CHANGELOG for any deprecations that might affect your code. Also confirm the include_dirs trick works with your build system, especially if you use a package manager other than npm.
Frequently asked questions
What is NaN in coding?
In this repository NaN means Native Abstractions for Node.js: a C++ header file shipped as the npm package nan, at version 2.29.0, whose purpose is to hold the logic needed to build native addons without inspecting NODE_MODULE_VERSION or hand-writing version macros.
What does NaN stand for in JS?
The package name is a short form of Native Abstractions for Node.js, and it has nothing to do with the NaN value the JavaScript language produces from arithmetic on non-numbers. It is a C++ compatibility header, not a language feature, and its documentation contains no material about numeric edge cases.
Why NaN !== NaN?
That is a property of the JavaScript NaN value and has no bearing on this project. nan is a native addon development header, and the only NaN it deals with is its own name, spelled as three lowercase letters rather than as the JavaScript constant.
What is the difference between NaN and null?
This repository does not cover JavaScript values. It ships the nan package, a single header file that lets a native addon compile across Node versions 8 through 26 by splitting version-specific implementations at 12 and 43.
nodejs is nan
nan is not part of Node.js. It is a separate package added as a dependency, and its manifest sets main to include_dirs.js, so requiring it in your build script yields the header path to place in your binding.gyp include_dirs list, which then behaves like an -I flag when the addon compiles.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nodejs-nan)Star history chart for your README
[](https://hysenlabs.com/projects/nodejs-nan)Was this useful?