| name | check-node-compat |
| description | Check compatibility with a new Node.js major version for this native C++ addon.
Use when a new Node.js major is released and needs to be added to the supported
matrix, or when asked to verify whether the addon works on a specific Node version.
Triggers: "add Node X support", "does this work on Node X", "new Node major",
"update Node version matrix", "Node compatibility".
|
Node.js Compatibility Check Skill
Goal
Determine what changes are needed to support a new Node.js major version in this
native C++ addon. The addon uses raw V8 APIs directly — there is no abstraction
layer shielding it from breaking changes. nan and node-addon-api are present
only as header path providers for the build system, not as API wrappers.
This means the V8 API scan is the highest-risk step. Everything else is mechanical.
The output is a concrete report: what is safe, what needs a mechanical change, and
what needs manual verification or a new CI run.
Step 1 — Identify the new V8 version
Each Node.js major embeds a specific V8 version. Find it with a web search:
Node.js X.0.0 release notes V8 version
Or check the official Node.js changelog at https://nodejs.org/en/blog/release/.
Record the V8 version (e.g., V8 13.0). This is the input to Step 2.
See references/research-sources.md for additional
sources to find the exact V8 version embedded in a given Node release.
Step 2 — Scan for raw V8 API changes (highest risk)
The source uses V8 APIs directly with no abstraction layer. Any V8 API rename,
removal, or signature change in the new version is a direct build break.
2a. Find existing version guards:
grep -rn "NODE_VERSION_v" src/
For each guard found, check whether the API it wraps has changed in the new V8
version. See references/repo-compat-surface.md
for the current guards and what they protect.
2b. Find direct V8 API calls most likely to change between versions:
grep -rn "v8::String::\|->IsExternal\|->IsString\|ExternalString\|NewFromUtf8\|Utf8Value" src/
grep -rn "GetIsolate\(\)\|GetCurrentContext\(\)\|isolate->Get\|isolate->Throw" src/
These are the V8 API families that have changed most frequently across Node majors.
Cross-reference hits against the V8 API diff for the old→new version:
https://github.com/v8/v8/compare/OLD.V-lkgr...NEW.V-lkgr
Focus on changes under include/ — those are the public API surface.
Web search template for a specific function:
V8 API "<function_name>" deprecated OR removed OR changed vNEW
See references/research-sources.md for V8 diff
and changelog sources.
Step 3 — Check header path providers
nan and node-addon-api are not API abstraction layers in this codebase — they
are used only to resolve the path to Node.js headers at build time:
binding.gyp uses require('nan') to locate Node headers for node-gypCMakeLists.txt uses require('node-addon-api').include for the CppUTest build
The check here is minimal: activate the new Node version (e.g. nvm use X), then
run both build steps to confirm headers resolve correctly:
npm run build
npm run test:native
If CppUTest is not installed locally, skip npm run test:native and rely on CI
to surface any header resolution failure for that path.
No API compatibility research is needed for these packages.
If either command fails with a header resolution error, upgrade the offending
package to a pinned stable version:
npm view nan version
npm view node-addon-api version
npm install nan@X.Y.Z
npm install node-addon-api@X.Y.Z
Do not use @latest — versions must be pinned.
Step 4 — Update the hardcoded version define in CMakeLists.txt
CMakeLists.txt contains -DNODE_VERSION_v18, which
drives the #if defined(...) guards found in Step 2.
- If Step 2 found no new API changes: no update needed — the current
else branch
already covers the new version.
- If Step 2 found a new API change requiring a new branch: add
#if defined(NODE_VERSION_vX) in src/iast_node.h and update the define in
CMakeLists.txt. Always update both files in the same commit.
Cleaning up obsolete guards: if the lowest version in the CI matrix has advanced
past the version a guard was written for (e.g., NODE_VERSION_v16 once Node 16 is
removed from the matrix), the guard and its older branch are dead code. Remove them
and simplify the macro to the surviving branch. Do this in a dedicated cleanup commit,
not mixed with the new version addition.
See references/repo-compat-surface.md for the
full picture of this define and the current guards.
Step 5 — Update the CI version matrix
Add the new Node version to the test matrices in
.github/workflows/build.yml.
See references/repo-compat-surface.md for
which specific jobs have version matrices and which have fixed pinned versions.
Step 6 — Produce the compatibility report
## Node X Compatibility Report
### V8 API scan
- Guards found: <list from grep, or "none">
- Unguarded V8 calls reviewed: <count reviewed>
- Status per guard/call: <safe / needs new branch / unknown>
Reason: <what changed in V8 X.Y, or "no change found in changelog">
### Obsolete guards
- <guard name>: obsolete since Node <Y> was removed from the matrix — <action: remove / keep>
- (or: none detected)
### Build system (nan / node-addon-api)
- Header resolution: OK / FAILED (upgrade needed)
- Action: none / upgrade <package> to X.Y.Z
### CMakeLists.txt
- NODE_VERSION define: <current> — <action: no change / update to NODE_VERSION_vX>
### CI Matrix (.github/workflows/build.yml)
- Jobs updated: <list>
### Verdict
SAFE TO ADD / NEEDS CHANGES / REQUIRES MANUAL VERIFICATION
Mark REQUIRES MANUAL VERIFICATION if any V8 API call could not be confirmed safe
from changelog research alone. State what the CI run will surface.
What this skill cannot guarantee
The definitive answer comes from running CI against the new Node version. Because
the code uses raw V8 APIs, a breaking change can exist without any changelog entry
if it was an undocumented internal. The green CI run on the new version is the
final sign-off.
