Skip to content

Migrate to native ESM #1479

@rowanmanning

Description

@rowanmanning

In April 2026, Node.js 20 goes end-of-life which means that all of the latest LTS versions of Node.js will support importing ESM from CommonJS. This is a potential opportunity to modernise this library.

What problem does this feature solve?

The varying module systems have caused us some annoyances over the years, see the test folder in this repo for an illustration of us trying to ensure Reliability Kit works well wherever. I think CommonJS can also be considered mostly legacy.

Ideal solution

We switch to native ESM and update our supported Node.js versions to allow:

^22.12 || ^24

These versions allow requiring ESM without the --experimental-require-module CLI flag. An issue is: we've never pinned at "greater than a minor version of this major" before, so it's a change to the way we specify versions. I'm personally OK with that but maybe you aren't?

We then rewrite all packages to use ESM. We'd probably also want to stop using default exports at the same time.

This is definitely a breaking change.

Alternatives

We could leave this as-is and avoid a little bit of churn. We could also wait until Node.js 22 goes end-of-life (2027-04-30) because every version of Node.js 24 supports requiring ESM from CommonJS.

We could also still include Node.js v20 if we pin it at ^20.19.

Metadata

Metadata

Assignees

No one assigned

    Labels

    breaking changeIndicates that the feature will require a major version bump.enhancementNew feature or request

    Type

    No type

    Projects

    Status

    📝 Planned

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions