Node.js 24 Migration Guide: ESM, Permission Model, and Test Runner Checklist

TL;DR

Node.js 24 is a migration worth treating as an engineering project, not a routine version bump. The risky work is rarely the install command itself. It is the interaction between ESM package loading, native dependencies, CI images, permission boundaries, test coverage, and the scripts your team has accumulated around builds, releases, and local development.

Use this guide to split the migration into a reversible checklist: inventory runtime usage, test ESM and CommonJS edges, trial the permission model around filesystem and network access, move more coverage onto the built-in test runner where it reduces dependency weight, and roll out Node 24 through CI before production traffic depends on it.

Quick Decision Table

Situation	Best migration posture	Why it matters
You publish libraries	Test Node 20, 22, and 24 in CI before changing engines	Consumers may still be on active LTS lines while early adopters validate Node 24.
You run production services	Canary Node 24 behind existing deploy rollback paths	Runtime differences should be reversible without a code rollback.
You are moving to ESM	Audit exports, conditional exports, dynamic import, and test tooling together	ESM failures often appear in tooling and transitive dependencies before app code.
You want stronger sandboxing	Trial the permission model in CI and local smoke tests first	Permission flags can expose hidden filesystem, child-process, or network assumptions.
Your test stack is heavy	Add focused node:test coverage before replacing a full runner	The built-in runner is useful, but migration should preserve watch, mocking, coverage, and reporter needs.

Migration Goals for Node.js 24

A good Node.js 24 migration has three goals. First, production and CI should run the same major runtime. Second, package boundaries should be explicit enough that ESM, CommonJS, and conditional exports behave predictably. Third, the team should learn whether newer runtime features can replace dependencies or harden deployment without forcing a risky rewrite.

Start with a baseline. Record your current Node version, package manager version, lockfile state, container base image, serverless runtime, and CI image. Then identify every place the runtime is pinned: .nvmrc, .node-version, volta, mise, Dockerfile, GitHub Actions setup, Vercel or other deployment settings, and package.json engines.

ESM and CommonJS Checklist

Node upgrades often surface module-boundary problems that were already present. Before changing production, run a clean install and test pass under Node 24 with dependency caches disabled.

Check these areas:

• type: "module" boundaries in every package of a monorepo.
• exports maps for libraries that publish both ESM and CommonJS entrypoints.
• Test setup files that still rely on require, __dirname, or implicit extension resolution.
• CLI scripts that are executed directly with shebangs.
• Dynamic imports that load JSON, TypeScript-transpiled output, or optional adapters.
• Bundler assumptions around module, main, browser, and conditional exports.

For libraries, avoid changing too many compatibility promises at once. If the real goal is Node 24 support, add it to CI first. If the real goal is an ESM-only release, treat that as a separate semver and documentation project.

Related PkgPulse guides:

• ESM-Only Package Migration Guide for Node.js Libraries
• Exports Map Guide for TypeScript npm Packages
• Corepack vs Volta vs mise Guide for Node Toolchain Pinning

Permission Model Trial Plan

The Node permission model is most useful when you introduce it as an observability and hardening exercise. Do not begin by locking down every production process. Begin by learning what the process actually touches.

A practical sequence:

1. Run smoke tests with the strictest permission flags you can tolerate.
2. Add only the filesystem paths, child processes, worker threads, and network access the app genuinely needs.
3. Separate build-time permissions from runtime permissions.
4. Document why each allowance exists.
5. Turn permission failures into CI signals before enforcing them in production.

Watch for hidden access in common places: template loading, certificate reads, local SQLite files, uploaded assets, native addon extraction, generated client files, and postinstall scripts. A failing permission check is not automatically a bug, but every allowance should have an owner.

Built-In Test Runner Checklist

The built-in node:test runner is a good fit for focused runtime, library, and integration checks. It can reduce toolchain weight for packages that do not need a browser-like environment or a large plugin ecosystem. It is not automatically a replacement for Vitest, Jest, or Playwright in every repo.

Use it where the value is clear:

• smoke tests that assert the app boots under Node 24;
• package export tests for ESM and CommonJS consumers;
• CLI tests that run real Node subprocesses;
• regression tests for permission flags and filesystem/network boundaries;
• small library suites where native Node assertions are enough.

Keep specialized runners where they still earn their keep. React component tests, browser automation, snapshot-heavy suites, and mocking-heavy application tests may be better left on the existing runner until the runtime migration is stable.

CI Rollout Steps

1. Add Node 24 to the matrix without removing current supported versions.
2. Run install, lint, tests, typecheck, and build on clean caches.
3. Fix native dependency or engine warnings before production rollout.
4. Add a package-export smoke test for libraries.
5. Add at least one node:test smoke test for service boot or CLI execution.
6. Trial permission flags in a non-blocking job, then make the job required after the allowlist is understood.
7. Update developer toolchain pins only after CI is green.

For published packages, update engines conservatively. Supporting Node 24 is different from requiring Node 24. Requiring the newest runtime can shrink your consumer base before the ecosystem has finished catching up.

Production Rollout and Rollback

Deploy Node 24 like infrastructure. Prefer a canary environment, one service, or one region before a full fleet cutover. Monitor startup time, memory, error rate, native addon loading, TLS/network behavior, queue workers, scheduled jobs, and build output size.

Have a rollback that does not depend on reverting application code. The safest migration lets you switch the runtime image or platform setting back to the previous major version while keeping the same app commit. If the rollback path is unclear, the migration is not ready for the highest-traffic surface.

Common Mistakes

The most common mistake is combining a runtime upgrade, ESM migration, test-runner migration, dependency cleanup, and container refresh into one large release. Each one is valuable, but stacking them makes failures hard to diagnose. Sequence the work so every production change has a narrow cause.

Another mistake is trusting local success over CI. Local machines often have cached builds, globally installed tools, and shell configuration that hides version drift. Node 24 should pass from a clean checkout, clean install, and clean build image before it becomes the default.

Bottom Line

Adopt Node.js 24 when your CI, module boundaries, permission assumptions, and rollback path are ready. The win is not just a newer runtime; it is a cleaner package boundary, a stronger test surface, and a deploy process that makes future Node upgrades less dramatic.