Native Abstractions for Node.js (NAN)

2.26.2 · active · verified Sun Apr 19

nan (Native Abstractions for Node.js) is a crucial C++ header-only library designed to provide a consistent compatibility layer for developing Node.js native add-ons. It expertly abstracts away the frequent and significant breaking changes introduced by updates to the V8 JavaScript engine and Node.js core APIs. This allows add-on developers to write C++ code that compiles and functions reliably across a broad spectrum of Node.js versions, spanning from legacy 0.8 releases up to the current Node.js 25. The current stable version is 2.26.2. Releases are generally aligned with new major Node.js LTS lines or critical V8 API shifts. Its primary differentiator is offering a stable C++ API surface, thereby eliminating the complex, version-specific conditional compilation macros developers would otherwise need to manage manually. Importantly, nan does not expose any direct JavaScript runtime APIs; its sole focus is on simplifying the development and maintenance of native modules.

Common errors

```
fatal error: nan.h: No such file or directory
```
cause The C++ compiler could not find the `nan.h` header file, indicating an incorrect or missing include path.

fix Ensure your `binding.gyp` file's `include_dirs` property correctly points to the `nan` installation path, typically by using `<!(node -e "require('nan')")`.
```
Error: The module 'your_addon_name.node' did not self-register.
```
cause This error occurs when a native add-on fails to initialize correctly, often due to an improperly defined `NODE_MODULE` macro or issues during linking.

fix Verify that your `NODE_MODULE` macro's arguments match your initialization function and the intended module name. Confirm that `node-gyp rebuild` completed without errors.
```
error: no matching function for call to 'v8::Object::Set(...)'
```
cause This type of error indicates that you are attempting to use a raw V8 API function that has changed its signature or behavior across Node.js/V8 versions, or you are using it incorrectly alongside `nan` abstractions.

fix Strictly rely on `Nan::` prefixed APIs (e.g., `Nan::SetMethod`, `Nan::New`) which are designed to abstract these V8 differences. Consult `nan` documentation for the correct wrapper functions.

Warnings

breaking Direct usage of V8 and Node.js N-API (without NAN's abstractions) is highly unstable across Node.js versions due to frequent V8 breaking changes and evolving Node.js internals. Code written for one Node.js version may fail to compile or run on another.
Fix: Consistently utilize `nan` to abstract V8 API differences, or strictly target a single Node.js LTS version and be prepared to update your native add-on code with each V8 upgrade.
gotcha Incorrect `binding.gyp` configuration, specifically the `include_dirs` entry, is a very common source of compilation failures for native add-ons.
Fix: Always ensure your `include_dirs` property in `binding.gyp` correctly uses `<!(node -e "require('nan')")` to dynamically locate the `nan` headers, preventing hardcoded paths that can break across environments.
gotcha Memory management within native add-ons, particularly with `v8::Local`, `Nan::Persistent`, and `Nan::HandleScope`, requires meticulous attention to avoid memory leaks, crashes, or undefined behavior.
Fix: Always use `Nan::HandleScope` within methods, carefully manage `Nan::Persistent` handles, and thoroughly understand V8's garbage collection semantics when dealing with native memory.

Install

npm install nan npm
yarn add nan yarn
pnpm add nan pnpm

Imports

NAN_INCLUDE_DIR
wrong:
```
"./node_modules/nan"
```
correct:
```
"<!(node -e \"require('nan')\")"
```
This expression is used within `binding.gyp` to dynamically retrieve the correct include path for NAN C++ headers, ensuring cross-platform and cross-version compatibility.
nan.h
```
#include <nan.h>
```
This is a C++ preprocessor directive used in your native add-on's C++ source files to access the NAN API. It is not a JavaScript import.
Nan::SetMethod
```
Nan::SetMethod(target, "methodName", MyMethod);
```
This represents a core C++ macro/function provided by NAN, which abstracts V8 API differences for exposing C++ methods to JavaScript. This is used within your C++ add-on code.

Quickstart

This quickstart demonstrates how to set up a basic Node.js native add-on using `nan`, including the `package.json`, `binding.gyp`, C++ source, and a simple JavaScript entry point. Run `npm install` and then `node index.js`.

/* package.json */
{
  "name": "nan-example-addon",
  "version": "1.0.0",
  "private": true,
  "gypfile": true,
  "dependencies": {
    "nan": "^2.26.2"
  },
  "scripts": {
    "install": "node-gyp rebuild"
  }
}

/* binding.gyp */
{
  "targets": [
    {
      "target_name": "myaddon",
      "sources": [ "src/addon.cc" ],
      "include_dirs": [
        "<!(node -e \"require('nan')\")"
      ]
    }
  ]
}

/* src/addon.cc */
#include <nan.h>

void Method(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  info.GetReturnValue().Set(Nan::New("world").ToLocalChecked());
}

void Initialize(v8::Local<v8::Object> exports) {
  Nan::SetMethod(exports, "hello", Method);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)

/* index.js */
const addon = require('./build/Release/myaddon.node');
console.log(addon.hello()); // Outputs: world

view raw JSON →