NAN 2.27.0 incompatible with V8 13.x (Electron 42 / Node 24): v8::External API breaking changes

[oalfroukh]

Environment

• NAN: 2.27.0
• Electron: 42.3.0 (V8 13.2.x)
• Node.js (system): 22.22.3
• OS: Windows 10 (also reproducible on other platforms)
• node-gyp: 12.3.0

Description

Building any NAN-based native addon against Electron 42 (V8 13.x) headers
fails due to breaking changes in v8::External API:

• v8::External::Value() now requires a v8::Isolate* parameter
• v8::External::New() signature changed

The errors originate inside NAN's own files:

• nan_callbacks_12_inl.h
• nan_implementation_12_inl.h

Error Output

nan_callbacks_12_inl.h(213,46): error C2660:
'v8::External::Value': function does not take 0 arguments
nan_implementation_12_inl.h(79,24): error C2660:
'v8::External::New': function does not take 2 arguments

Minimal Reproduction

binding.gyp

{
  "targets": [{
    "target_name": "hello",
    "sources": [ "hello.cc" ],
    "include_dirs": [ "<!(node -e \"require('nan')\")" ]
  }]
}

hello.cc

#include <nan.h>

NAN_METHOD(Hello) {
    info.GetReturnValue().Set(
        Nan::New("hello world").ToLocalChecked()
    );
}

NAN_MODULE_INIT(Init) {
    NAN_EXPORT(target, Hello);
}

NODE_MODULE(hello, Init)

package.json

{
  "name": "nan-repro",
  "version": "1.0.0",
  "dependencies": { "nan": "2.27.0" },
  "scripts": { "build": "node-gyp rebuild" }
}

Steps to reproduce:

npm install
# Download Electron 42 headers
npx node-gyp rebuild --target=42.3.0 --dist-url=https://electronjs.org/headers

Root Cause

In nan_callbacks_12_inl.h, NAN calls ->Value() with no arguments.
In V8 13.x (shipped with Electron 42 / Node 24), v8::External::Value()
now requires a v8::Isolate*:

// V8 12.x (works)
void* Value() const;

// V8 13.x (breaking change)
void* Value(Isolate* isolate) const;

Expected Behavior

NAN should handle the v8::External API change in V8 13.x, as it has
handled previous V8 API changes, so addons using NAN compile against
Electron 42 / Node 24 without modification.

Notes

This affects all NAN-based addons targeting Electron 42+, which is
a significant portion of the Electron native addon ecosystem.

[oalfroukh]

Hi @gdavidkov

Do you think yr PR #1015 can fix this issue?

[gdavidkov]

Hi @oalfroukh — yes, #1015 covers both errors you listed. The PR routes the New and Value calls through helpers that pass v8::kExternalPointerTypeTagDefault when V8 exposes the new tagged API, so the errors in nan_implementation_12_inl.h and nan_callbacks_12_inl.h are gone.

If you want to unblock builds in the meantime, you can point your package.json at the branch:

"nan": "github:gdavidkov/nan#fix/external-value-v8-13"

[agracio]

While PR is pending you can use an unofficial branch that has this PR merged.

package.json

"dependencies": {
    "nan": "npm:@agracio/nan@^2.26.3"
},