Handling native addon compatibility during Node.js version rollbacks

Answering the Question

The most reliable way to keep native C++ addons working after you roll back to an older Node.js release is to rebuild them with npm rebuild (or npm ci if you prefer a clean install). The runtime does not pre‑detect ABI mismatches; a mismatch only surfaces as a load‑time error when the addon is required.

Runtime Behavior

• Node.js checks the process.versions.modules value against the binary’s NODE_MODULE_VERSION embedded in the addon.
• If the numbers differ, the require call throws an Error: The module was compiled against Node.js version X.x.x message.
• No earlier warning or diagnostic is provided by the engine.

Rebuild Strategy

1. Switch to the desired Node.js version with nvm use or n.

   nvm use 14.17.0   # example
   

2. Run a full rebuild of all native modules:

   npm rebuild
   

   This invokes node-gyp for each package that declares a binding.gyp and compiles against the current ABI.
3. Alternatively, if you want a clean slate, use npm ci (requires a package-lock.json and will reinstall everything).
4. If prebuilt binaries are available (via node-pre-gyp or prebuild), you can fetch the correct binary with:

   npm install --build-from-source
   

   This forces node-gyp to build from source if no matching prebuilt exists.

Verification

• Check the ABI number:

  node -e "console.log(process.versions.modules)"
  

  It should match the ABI expected for the Node.js version you are running.
• Test a single addon load:

  node -e "require('your-addon')"
  

  No error means the rebuild succeeded.
• Run npm ls to ensure no packages are reported as missing or broken.

When a Full Rebuild Might Not Be Needed

If you know that the project relies on a small set of native modules and you have prebuilt binaries for the target Node.js version, you can skip a full reinstall:

• Run npm install --build-from-source for just those modules.
• Or, if the binaries are already present in the node_modules folder, a simple npm install will copy them without recompilation.

Additional Diagnostic Detail

To fine‑tune the rebuild approach, it helps to know which native modules you have. If you provide that list, we can suggest whether prebuilt binaries exist for the target ABI, potentially saving a full rebuild.