Node.js Runtime Upgrade Checklist
A pre-flight checklist for major Node.js LTS upgrades. It covers deprecated APIs, native addon rebuilds, ESM changes, image and CI parity, and canary rollout.
When to Use This Checklist
Use this checklist before upgrading a Node.js application across a major LTS version. Major Node releases remove deprecated APIs, change the bundled V8 engine, and shift the native addon ABI. The module-system landscape (CommonJS versus ECMAScript Modules) also evolves between versions. A pre-flight pass catches these before deployment.
How to Use This Checklist
Pin the current version, then review the target release notes for removed and deprecated APIs. Establish a green test baseline and audit dependencies, paying special attention to native addons that must be recompiled against the new ABI. Update the base container image and CI matrix together so local, build, and runtime versions match. Run the full suite plus integration tests on the target runtime.
Roll out behind a canary, watching event-loop lag and memory, and keep the prior image ready.
What Good Looks Like
A clean upgrade pins the new version in .nvmrc, engines, the container image, and the CI matrix. Native addons are rebuilt, dependencies are confirmed compatible, and npm audit shows no unaddressed critical advisories. Tests pass on the target runtime and a canary shows stable event-loop and memory behavior before full rollout.
Common Pitfalls
The most common failure is a native addon that silently fails because it was compiled for the old ABI. Teams also let local, CI, and production Node versions drift apart. ESM and CommonJS interop changes can break imports in non-obvious ways. Skipping a canary hides memory or event-loop regressions until peak load.
Related Resources
See the twelve-factor app for runtime parity, the test pyramid for your safety net, and canary release practices for rollout. Static application security testing in CI covers the dependency audit.