# nodejs/nan

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/nodejs-nan).**

3,351 stars · 527 forks · C++ · mit

## Links

- GitHub: https://github.com/nodejs/nan
- awesome-repositories: https://awesome-repositories.com/repository/nodejs-nan.md

## Topics

`node` `nodejs`

## Description

This project is a compatibility layer and abstraction library for building native C++ addons for Node.js. It provides a consistent C++ API that allows a single codebase to compile against multiple versions of the V8 JavaScript engine by hiding version-specific differences behind macros and inline functions.

The toolkit differentiates itself through specialized wrappers and managers, including a monadic wrapper for handles to avoid explicit null checks, a persistent reference manager for objects that must survive handle scope disposal, and a buffer abstraction API for version-compatible memory management.

It covers a broad range of native development capabilities, including the wrapping of C++ classes as JavaScript objects, the execution of native tasks on background threads via asynchronous worker patterns, and the management of memory through handle scopes and garbage collection hooks. It also provides utilities for data type conversion, string encoding, and the execution of JavaScript scripts from native code.

This is a header-only library.

## Tags

### Programming Languages & Runtimes

- [Engine API Abstractions](https://awesome-repositories.com/f/programming-languages-runtimes/engine-api-abstractions.md) — Hides V8 API differences across Node versions behind a consistent set of C++ macros and inline functions.
- [Node.js Native Addons](https://awesome-repositories.com/f/programming-languages-runtimes/node-js-native-addons.md) — Provides a consistent C++ API for building native Node.js addons that work across multiple V8 and Node.js versions.
- [Callback Lifecycle Management](https://awesome-repositories.com/f/programming-languages-runtimes/callback-lifecycle-management.md) — Prevents function handles from being garbage collected to ensure safe execution during asynchronous native tasks. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Node.js Buffer Encodings](https://awesome-repositories.com/f/programming-languages-runtimes/dynamic-strings/memory-management/string-encoding-converters/node-js-buffer-encodings.md) — Provides version-compatible APIs for allocating and converting Node.js Buffer objects and string encodings.
- [Native Memory Lifecycle Management](https://awesome-repositories.com/f/programming-languages-runtimes/language-interoperability/native-c-interoperability/native-memory-lifecycle-management.md) — Manages the memory lifecycle of C++ classes wrapped as JavaScript objects across V8 handle scopes.
- [Native Method Registration](https://awesome-repositories.com/f/programming-languages-runtimes/native-method-registration.md) — Binds native C++ functions and data structures to JavaScript objects using version-compatible templates. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Native Object Wrapping](https://awesome-repositories.com/f/programming-languages-runtimes/native-object-wrapping.md) — Exposes C++ classes as JavaScript objects using base wrapper templates for constructors and method dispatch.
- [Buffer Abstraction Layers](https://awesome-repositories.com/f/programming-languages-runtimes/node-js-file-system-extensions/node-js-api-compatibility-layers/buffer-abstraction-layers.md) — Ships an abstraction API for allocating, copying, and freeing Node.js Buffers across different versions.
- [Buffer Abstractions](https://awesome-repositories.com/f/programming-languages-runtimes/node-js-file-system-extensions/node-js-api-compatibility-layers/buffer-abstractions.md) — Provides a version-compatible Buffer abstraction API for consistent memory management across Node.js versions.
- [Native Addon Abstraction Frameworks](https://awesome-repositories.com/f/programming-languages-runtimes/node-js-native-addons/native-addon-abstraction-frameworks.md) — Provides a consistent C++ API abstraction for building native Node.js addons across multiple V8 versions.
- [Native Async Worker Patterns](https://awesome-repositories.com/f/programming-languages-runtimes/node-js-worker-thread-pools/asynchronous-worker-functions/native-async-worker-patterns.md) — Implements asynchronous worker patterns to execute heavy native tasks on background threads.
- [V8 Object Wrapping](https://awesome-repositories.com/f/programming-languages-runtimes/object-lifecycle-managers/v8-object-wrapping.md) — Exposes C++ classes as JavaScript objects with consistent lifecycle management across engine versions.
- [String Encoding Converters](https://awesome-repositories.com/f/programming-languages-runtimes/dynamic-strings/memory-management/string-encoding-converters.md) — Converts between JavaScript string and byte encodings consistently across different V8 versions. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Value Construction Helpers](https://awesome-repositories.com/f/programming-languages-runtimes/javascript-runtime-compatibility-layers/value-construction-helpers.md) — Constructs JavaScript primitives and objects using a unified helper to maintain cross-version compatibility. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Native-to-Script Function Invocations](https://awesome-repositories.com/f/programming-languages-runtimes/language-interoperability/native-c-interoperability/c-function-bindings/argument-transformation-functions/native-to-script-function-invocations.md) — Calls JavaScript functions from native code with support for context awareness and custom argument handling. ([source](https://github.com/nodejs/nan/blob/master/CHANGELOG.md))
- [Object Lifetime Management](https://awesome-repositories.com/f/programming-languages-runtimes/programming-language-varieties/programming-languages/language-specific-resources/language-tutorials/c-c-tutorials/object-management/object-lifetime-management.md) — Controls the lifetime of JavaScript objects by binding them to references to prevent premature garbage collection. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Temporary Scope Management](https://awesome-repositories.com/f/programming-languages-runtimes/programming-language-varieties/programming-languages/language-specific-resources/language-tutorials/c-c-tutorials/object-management/scoped-lifecycle-managers/temporary-scope-management.md) — Creates and disposes V8 handle scopes to safely manage object references across multiple Node versions.
- [Runtime Exception Handling](https://awesome-repositories.com/f/programming-languages-runtimes/runtime-exception-handling.md) — Creates and throws typed JavaScript exceptions using helpers that abstract engine version differences. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Cross-Environment Value Generators](https://awesome-repositories.com/f/programming-languages-runtimes/runtime-execution-environments/runtime-environments/language-runtimes/javascript-environments/cross-environment-value-generators.md) — Produces common JavaScript types like objects and booleans using a version-agnostic interface. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Monadic Handle Wrappers](https://awesome-repositories.com/f/programming-languages-runtimes/type-wrappers/monadic-handle-wrappers.md) — Implements monadic wrappers for V8 handles to safely propagate emptiness without explicit null checks.
- [V8 Engine Memory Management](https://awesome-repositories.com/f/programming-languages-runtimes/v8-engine-memory-management.md) — Allows native addons to adjust external memory tracking and register callbacks for V8 garbage collection events. ([source](https://github.com/nodejs/nan/blob/master/CHANGELOG.md))

### Software Engineering & Architecture

- [Native Object Accessors](https://awesome-repositories.com/f/software-engineering-architecture/object-mapping-apis/native-object-accessors.md) — Binds native C++ class instances to JavaScript objects for use within the script environment. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Native-Backed JavaScript Functions](https://awesome-repositories.com/f/software-engineering-architecture/architectural-design-patterns/design-patterns/functional-design-patterns/functional-programming/closures/function-to-closure-coercions/native-function-closures/native-backed-javascript-functions.md) — Exposes C++ functions as native-backed JavaScript functions within objects. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Asynchronous Background Processors](https://awesome-repositories.com/f/software-engineering-architecture/asynchronous-background-processors.md) — Offloads time-consuming native tasks to background threads to maintain responsiveness on the main JavaScript thread. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Cross-Version Compatibility Gating](https://awesome-repositories.com/f/software-engineering-architecture/cross-version-compatibility-gating.md) — Hides V8 API differences behind macros and inline functions to ensure cross-version compatibility.
- [V8 API Abstraction Layers](https://awesome-repositories.com/f/software-engineering-architecture/cross-version-compatibility-gating/v8-api-abstraction-layers.md) — Acts as a compatibility layer allowing C++ code to compile against multiple versions of the V8 engine.
- [Runtime API Wrappers](https://awesome-repositories.com/f/software-engineering-architecture/legacy-compatibility-wrappers/runtime-api-wrappers.md) — Hides V8 API version differences behind a single set of macros and inline functions for cross-version compatibility.
- [Garbage Collection Prevention](https://awesome-repositories.com/f/software-engineering-architecture/memory-usage-analysis/memory-leak-prevention/callback-leak-preventers/garbage-collection-prevention.md) — Wraps function handles to ensure they are not garbage collected while background work is still in progress. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Asynchronous Task Managers](https://awesome-repositories.com/f/software-engineering-architecture/asynchronous-task-managers.md) — Coordinates concurrent background operations and signals progress from native threads back to the main event loop. ([source](https://github.com/nodejs/nan/blob/master/CHANGELOG.md))
- [Native-to-JS Thread Dispatching](https://awesome-repositories.com/f/software-engineering-architecture/background-thread-dispatchers/thread-safe-dispatchers/ui-thread-schedulers/worker-to-ui-thread-messaging/native-to-js-thread-dispatching.md) — Provides a helper to run C++ work on background threads and invoke JavaScript callbacks upon completion.
- [Value Type Conversions](https://awesome-repositories.com/f/software-engineering-architecture/data-schema-validation/data-type-validation/value-type-conversions.md) — Translates V8 engine value types into native C++ types with return signals for success tracking. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Monadic Error Handling](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling.md) — Wraps engine handles in monadic Maybe types to ensure safe accessor methods and propagate emptiness.
- [Monadic Containers](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling/monadic-containers.md) — Encapsulates potentially empty V8 handles using monadic containers to avoid explicit null checks.
- [Throw-Based Error Handlers](https://awesome-repositories.com/f/software-engineering-architecture/error-handling-strategies/monadic-error-handling/throw-based-error-handlers.md) — Processes typed errors by abstracting the creation and throwing mechanisms of the underlying JavaScript engine. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Reference Lifecycle Management](https://awesome-repositories.com/f/software-engineering-architecture/memory-usage-analysis/memory-leak-prevention/reference-lifecycle-management.md) — Manages the lifecycle of persistent V8 object references that must survive handle scope disposal.
- [V8 Handle Persistence](https://awesome-repositories.com/f/software-engineering-architecture/memory-usage-analysis/memory-leak-prevention/reference-lifecycle-management/v8-handle-persistence.md) — Provides a persistent reference manager for V8 objects that must survive handle scope disposal. ([source](https://github.com/nodejs/nan/blob/master/CHANGELOG.md))
- [Asynchronous Task Executors](https://awesome-repositories.com/f/software-engineering-architecture/task-scheduling/asynchronous-schedulers/asynchronous-thread-schedulers/custom-thread-executors/asynchronous-task-executors.md) — Manages the scheduling and execution of asynchronous native tasks using thread pools and lifecycle helpers. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Typed Error Objects](https://awesome-repositories.com/f/software-engineering-architecture/typed-error-objects.md) — Generates typed JavaScript exceptions using helpers that abstract engine-specific error constructors.

### Data & Databases

- [Async Callback Persistence](https://awesome-repositories.com/f/data-databases/callback-data-stores/async-callback-persistence.md) — Protects function handles from garbage collection to ensure they remain valid across asynchronous execution cycles. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Execution Scopes](https://awesome-repositories.com/f/data-databases/database-query-builders/query-scopes/synchronization-scopes/execution-scopes.md) — Manages the lifecycle of local V8 handles using escapable scopes to prevent memory leaks. ([source](https://github.com/nodejs/nan/blob/master/CHANGELOG.md))
- [Binary Buffer Management](https://awesome-repositories.com/f/data-databases/shared-memory-data-exchange/direct-memory-data-transfer/typed-array-buffers/binary-buffer-management.md) — Implements a version-agnostic interface for allocating and manipulating binary data and typed arrays.
- [Typed Arrays](https://awesome-repositories.com/f/data-databases/shared-memory-data-exchange/direct-memory-data-transfer/typed-array-buffers/binary-buffer-management/typed-arrays.md) — Provides helper classes to access the raw binary contents of JavaScript typed arrays from native code. ([source](https://github.com/nodejs/nan/blob/master/CHANGELOG.md))

### Operating Systems & Systems Programming

- [Async Worker Patterns](https://awesome-repositories.com/f/operating-systems-systems-programming/async-worker-patterns.md) — Implements an asynchronous worker pattern to run native C++ tasks on background threads with callbacks to JavaScript.
- [Binary Buffer Managers](https://awesome-repositories.com/f/operating-systems-systems-programming/kernel-core-internals/process-and-memory-management/memory-management/buffer-and-cache-management/binary-buffer-managers.md) — Allocates and copies memory buffers through a version-compatible API for native addon development. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Native Property Accessors](https://awesome-repositories.com/f/operating-systems-systems-programming/kernel-core-internals/system-programming-primitives/system-abstractions/native-interoperability-bindings/native-system-integrations/native-property-accessors.md) — Defines object properties with custom getters and setters to link native C++ data to JavaScript accessors. ([source](https://github.com/nodejs/nan/blob/master/CHANGELOG.md))
- [Persistent Object References](https://awesome-repositories.com/f/operating-systems-systems-programming/persistent-object-references.md) — Provides a persistent reference manager to ensure V8 objects survive handle scope disposal until explicitly freed.

### Web Development

- [Persistent Handle Management](https://awesome-repositories.com/f/web-development/component-references/persistent-handle-management.md) — Holds V8 object references that outlive handle scope disposal until they are explicitly freed. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))

### Part of an Awesome List

- [Native Type Converters](https://awesome-repositories.com/f/awesome-lists/data/json-processing/native-type-converters.md) — Translates V8 engine value types into native C++ types with success/failure signaling. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))
- [Native Module Definitions](https://awesome-repositories.com/f/awesome-lists/devtools/native-integration/native-module-bridges/native-module-definitions.md) — Defines the initialization function and exports the methods accessible to the JavaScript environment. ([source](https://cdn.jsdelivr.net/gh/nodejs/nan@main/README.md))