# nodejs/nan architecture

> Architecture diagram of the GitHub repository nodejs/nan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nodejs/nan
- Repository: https://github.com/nodejs/nan

## Overview

NAN is a header-only C++ compatibility layer for Node.js native add-ons, presenting a stable, newer-style interface over changing V8 and Node APIs. The principal workflow is that an add-on includes `nan.h` and uses its wrappers to expose JavaScript-facing methods and work with V8 values; NAN selects version-specific implementations where needed. The graph also preserves major documented capabilities such as callbacks, handles, persistent references, and object wrapping. Source excerpts are partial, so unsampled subsystem relationships are omitted rather than inferred.

Main entry points: [`nan.h`](https://github.com/nodejs/nan/blob/main/nan.h) (NAN facade), [`nan_callbacks.h`](https://github.com/nodejs/nan/blob/main/nan_callbacks.h) (Callback abstractions), [`nan_new.h`](https://github.com/nodejs/nan/blob/main/nan_new.h) (Value factories), [`nan_maybe_43_inl.h`](https://github.com/nodejs/nan/blob/main/nan_maybe_43_inl.h) (Modern maybe API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Addon API"]
  node_nan["NAN facade<br/>[nan.h]"]
  node_callbacks["Callback abstractions<br/>[nan_callbacks.h]"]
  node_modern_callbacks["Modern callbacks"]
  node_legacy_callbacks["Legacy callbacks"]
end

subgraph group_compat["Compatibility Layer"]
  node_modern_impl["Modern implementations"]
  node_legacy_impl["Legacy implementations"]
  node_new["Value factories<br/>[nan_new.h]"]
  node_maybe_modern["Modern maybe API<br/>[nan_maybe_43_inl.h]"]
  node_maybe_legacy["Legacy maybe API"]
  node_own_property["Property helper"]
end

subgraph group_values["Values and State"]
  node_converters["Type converters<br/>[nan_converters.h]"]
  node_json["JSON helpers<br/>[nan_json.h]"]
  node_strings["String and bytes<br/>[nan_string_bytes.h]"]
  node_typedarray["Typed array contents"]
  node_persistent12["Modern persistent refs"]
  node_persistentpre["Legacy persistent refs"]
  node_weak["Weak references<br/>[nan_weak.h]"]
end

subgraph group_utilities["Addon Utilities"]
  node_objectwrap["Object wrapping<br/>[nan_object_wrap.h]"]
  node_scriptorigin["Script origin<br/>[nan_scriptorigin.h]"]
end

node_author(("Addon developer"))
node_v8(("Node.js and V8"))

node_author -->|"includes"| node_nan
node_nan -->|"includes"| node_callbacks
node_nan -->|"includes"| node_new
node_nan -->|"includes"| node_maybe_modern
node_nan -->|"includes"| node_maybe_legacy
node_nan -->|"includes"| node_converters
node_nan -->|"includes"| node_json
node_nan -->|"includes"| node_strings
node_nan -->|"includes"| node_typedarray
node_nan -->|"includes"| node_persistent12
node_nan -->|"includes"| node_persistentpre
node_nan -->|"includes"| node_weak
node_nan -->|"includes"| node_objectwrap
node_nan -->|"includes"| node_scriptorigin
node_callbacks -->|"selects by version"| node_modern_callbacks
node_callbacks -->|"selects by version"| node_legacy_callbacks
node_new -->|"selects by version"| node_modern_impl
node_new -->|"selects by version"| node_legacy_impl
node_maybe_modern -->|"uses helper"| node_own_property
node_maybe_legacy -->|"uses helper"| node_own_property
node_nan -->|"abstracts APIs"| node_v8

click node_nan "https://github.com/nodejs/nan/blob/main/nan.h"
click node_callbacks "https://github.com/nodejs/nan/blob/main/nan_callbacks.h"
click node_modern_callbacks "https://github.com/nodejs/nan/blob/main/nan_callbacks_12_inl.h"
click node_legacy_callbacks "https://github.com/nodejs/nan/blob/main/nan_callbacks_pre_12_inl.h"
click node_modern_impl "https://github.com/nodejs/nan/blob/main/nan_implementation_12_inl.h"
click node_legacy_impl "https://github.com/nodejs/nan/blob/main/nan_implementation_pre_12_inl.h"
click node_new "https://github.com/nodejs/nan/blob/main/nan_new.h"
click node_maybe_modern "https://github.com/nodejs/nan/blob/main/nan_maybe_43_inl.h"
click node_maybe_legacy "https://github.com/nodejs/nan/blob/main/nan_maybe_pre_43_inl.h"
click node_own_property "https://github.com/nodejs/nan/blob/main/nan_define_own_property_helper.h"
click node_converters "https://github.com/nodejs/nan/blob/main/nan_converters.h"
click node_json "https://github.com/nodejs/nan/blob/main/nan_json.h"
click node_strings "https://github.com/nodejs/nan/blob/main/nan_string_bytes.h"
click node_typedarray "https://github.com/nodejs/nan/blob/main/nan_typedarray_contents.h"
click node_persistent12 "https://github.com/nodejs/nan/blob/main/nan_persistent_12_inl.h"
click node_persistentpre "https://github.com/nodejs/nan/blob/main/nan_persistent_pre_12_inl.h"
click node_weak "https://github.com/nodejs/nan/blob/main/nan_weak.h"
click node_objectwrap "https://github.com/nodejs/nan/blob/main/nan_object_wrap.h"
click node_scriptorigin "https://github.com/nodejs/nan/blob/main/nan_scriptorigin.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nan,node_callbacks,node_modern_callbacks,node_legacy_callbacks toneBlue
class node_modern_impl,node_legacy_impl,node_new,node_maybe_modern,node_maybe_legacy,node_own_property toneAmber
class node_converters,node_json,node_strings,node_typedarray,node_persistent12,node_persistentpre,node_weak toneMint
class node_objectwrap,node_scriptorigin toneRose
class node_author,node_v8 toneIndigo
```

## Components

### Addon API

- [NAN facade](https://github.com/nodejs/nan/blob/main/nan.h): `nan.h`
- [Callback abstractions](https://github.com/nodejs/nan/blob/main/nan_callbacks.h): `nan_callbacks.h`
- [Modern callbacks](https://github.com/nodejs/nan/blob/main/nan_callbacks_12_inl.h): `nan_callbacks_12_inl.h`
- [Legacy callbacks](https://github.com/nodejs/nan/blob/main/nan_callbacks_pre_12_inl.h): `nan_callbacks_pre_12_inl.h`

### Compatibility Layer

- [Modern implementations](https://github.com/nodejs/nan/blob/main/nan_implementation_12_inl.h): `nan_implementation_12_inl.h`
- [Legacy implementations](https://github.com/nodejs/nan/blob/main/nan_implementation_pre_12_inl.h): `nan_implementation_pre_12_inl.h`
- [Value factories](https://github.com/nodejs/nan/blob/main/nan_new.h): `nan_new.h`
- [Modern maybe API](https://github.com/nodejs/nan/blob/main/nan_maybe_43_inl.h): `nan_maybe_43_inl.h`
- [Legacy maybe API](https://github.com/nodejs/nan/blob/main/nan_maybe_pre_43_inl.h): `nan_maybe_pre_43_inl.h`
- [Property helper](https://github.com/nodejs/nan/blob/main/nan_define_own_property_helper.h): `nan_define_own_property_helper.h`

### Values and State

- [Type converters](https://github.com/nodejs/nan/blob/main/nan_converters.h): `nan_converters.h`
- [JSON helpers](https://github.com/nodejs/nan/blob/main/nan_json.h): `nan_json.h`
- [String and bytes](https://github.com/nodejs/nan/blob/main/nan_string_bytes.h): `nan_string_bytes.h`
- [Typed array contents](https://github.com/nodejs/nan/blob/main/nan_typedarray_contents.h): `nan_typedarray_contents.h`
- [Modern persistent refs](https://github.com/nodejs/nan/blob/main/nan_persistent_12_inl.h): `nan_persistent_12_inl.h`
- [Legacy persistent refs](https://github.com/nodejs/nan/blob/main/nan_persistent_pre_12_inl.h): `nan_persistent_pre_12_inl.h`
- [Weak references](https://github.com/nodejs/nan/blob/main/nan_weak.h): `nan_weak.h`

### Addon Utilities

- [Object wrapping](https://github.com/nodejs/nan/blob/main/nan_object_wrap.h): `nan_object_wrap.h`
- [Script origin](https://github.com/nodejs/nan/blob/main/nan_scriptorigin.h): `nan_scriptorigin.h`

### Other components

- **Addon developer**
- **Node.js and V8**

## Connections

- Addon developer → NAN facade: includes (evidence: `README.md`)
- NAN facade → Callback abstractions: includes (evidence: `nan.h`)
- NAN facade → Value factories: includes (evidence: `nan.h`)
- NAN facade → Modern maybe API: includes (evidence: `nan.h`)
- NAN facade → Legacy maybe API: includes (evidence: `nan.h`)
- NAN facade → Type converters: includes (evidence: `nan.h`)
- NAN facade → JSON helpers: includes (evidence: `nan.h`)
- NAN facade → String and bytes: includes (evidence: `nan.h`)
- NAN facade → Typed array contents: includes (evidence: `nan.h`)
- NAN facade → Modern persistent refs: includes (evidence: `nan.h`)
- NAN facade → Legacy persistent refs: includes (evidence: `nan.h`)
- NAN facade → Weak references: includes (evidence: `nan.h`)
- NAN facade → Object wrapping: includes (evidence: `nan.h`)
- NAN facade → Script origin: includes (evidence: `nan.h`)
- Callback abstractions → Modern callbacks: selects by version (evidence: `nan_callbacks.h`)
- Callback abstractions → Legacy callbacks: selects by version (evidence: `nan_callbacks.h`)
- Value factories → Modern implementations: selects by version (evidence: `nan_new.h`)
- Value factories → Legacy implementations: selects by version (evidence: `nan_new.h`)
- Modern maybe API → Property helper: uses helper (evidence: `nan_maybe_43_inl.h`)
- Legacy maybe API → Property helper: uses helper (evidence: `nan_maybe_pre_43_inl.h`)
- NAN facade → Node.js and V8: abstracts APIs (evidence: `README.md`)
