{"id":11378,"library":"nan","title":"Native Abstractions for Node.js (NAN)","description":"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.","status":"active","version":"2.26.2","language":"javascript","source_language":"en","source_url":"git://github.com/nodejs/nan","tags":["javascript"],"install":[{"cmd":"npm install nan","lang":"bash","label":"npm"},{"cmd":"yarn add nan","lang":"bash","label":"yarn"},{"cmd":"pnpm add nan","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for compiling native add-ons, which depend on NAN headers.","package":"node-gyp","optional":false}],"imports":[{"note":"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.","wrong":"\"./node_modules/nan\"","symbol":"NAN_INCLUDE_DIR","correct":"\"<!(node -e \\\"require('nan')\\\")\""},{"note":"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.","symbol":"nan.h","correct":"#include <nan.h>"},{"note":"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.","symbol":"Nan::SetMethod","correct":"Nan::SetMethod(target, \"methodName\", MyMethod);"}],"quickstart":{"code":"/* package.json */\n{\n  \"name\": \"nan-example-addon\",\n  \"version\": \"1.0.0\",\n  \"private\": true,\n  \"gypfile\": true,\n  \"dependencies\": {\n    \"nan\": \"^2.26.2\"\n  },\n  \"scripts\": {\n    \"install\": \"node-gyp rebuild\"\n  }\n}\n\n/* binding.gyp */\n{\n  \"targets\": [\n    {\n      \"target_name\": \"myaddon\",\n      \"sources\": [ \"src/addon.cc\" ],\n      \"include_dirs\": [\n        \"<!(node -e \\\"require('nan')\\\")\"\n      ]\n    }\n  ]\n}\n\n/* src/addon.cc */\n#include <nan.h>\n\nvoid Method(const Nan::FunctionCallbackInfo<v8::Value>& info) {\n  info.GetReturnValue().Set(Nan::New(\"world\").ToLocalChecked());\n}\n\nvoid Initialize(v8::Local<v8::Object> exports) {\n  Nan::SetMethod(exports, \"hello\", Method);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)\n\n/* index.js */\nconst addon = require('./build/Release/myaddon.node');\nconsole.log(addon.hello()); // Outputs: world\n","lang":"javascript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"Incorrect `binding.gyp` configuration, specifically the `include_dirs` entry, is a very common source of compilation failures for native add-ons.","severity":"gotcha","affected_versions":">=0.8"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your `binding.gyp` file's `include_dirs` property correctly points to the `nan` installation path, typically by using `<!(node -e \"require('nan')\")`.","cause":"The C++ compiler could not find the `nan.h` header file, indicating an incorrect or missing include path.","error":"fatal error: nan.h: No such file or directory"},{"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.","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.","error":"Error: The module 'your_addon_name.node' did not self-register."},{"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.","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.","error":"error: no matching function for call to 'v8::Object::Set(...)'"}],"ecosystem":"npm"}