●Change8

Migrating to Node.js v20.19.0

Version v20.19.0 introduces 2 breaking changes. This guide details how to update your code.

Released: 3/13/2025

2
Breaking Changes
4
Migration Steps
6
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

requireprocess.features.require_moduleworker.postMessageToThreadchild_processcryptomodule-sync

Breaking Changes

●Issue #1

require(esm) is now enabled by default on v20.x. While intended to be backward compatible, it changes the behavior of require() when targeting ES modules, which may now return a namespace object instead of throwing ERR_REQUIRE_ESM. Use --no-experimental-require-module to revert if regressions occur.

●Issue #2

Module syntax detection is now enabled by default. Ambiguous .js files without a package.json 'type' field may now be interpreted as ES modules if they contain ESM syntax, which could change execution behavior for previously failing or ambiguous scripts.

Migration Steps

  1. 1
    If using v20.x and experiencing issues with require() loading ES modules, use the --no-experimental-require-module flag.
  2. 2
    To avoid the performance penalty of module syntax detection, explicitly add 'type': 'module' or 'type': 'commonjs' to your package.json.
  3. 3
    If module syntax detection causes issues, use the --no-experimental-detect-module flag.
  4. 4
    Update any code relying on ERR_REQUIRE_ESM to handle the new behavior where require() may succeed or throw ERR_REQUIRE_ASYNC_MODULE.

Release Summary

This release enables require(esm) and module syntax detection by default on Node.js v20.x. It also introduces the postMessageToThread worker API and updates several core dependencies including ICU, NSS, and Corepack.

Need More Details?

View the full release notes and all changes for Node.js v20.19.0.

View Full Changelog