feat!: convert the package to ESM only by cryptodev-2s · Pull Request #323 · MetaMask/utils

cryptodev-2s · 2026-09-04T19:15:29Z

Top of stack #315, on #322.

Core is moving to an ESM only monorepo (MetaMask/core#9536), so this package should arrive already converted rather than landing as the only hybrid one in it.

Breaking

require('@metamask/utils') now fails with ERR_REQUIRE_ESM. main and module are gone, and both . and ./node resolve through exports to a single ./dist/*.js with ./dist/*.d.ts types. Consumers already using import are unaffected.

	Before	After
build	`ts-bridge`	`tsc`
output	`.cjs` + `.mjs` + `.d.cts` + `.d.mts`	`.js` + `.d.ts`
`@ts-bridge/cli`	yes	removed (`rimraf` added for cleaning)

ts-bridge exists to emit both formats, so it goes with the CJS half.

Import specifiers

102 relative specifiers across 45 files gained explicit .js extensions, which ESM requires; directories resolve to /index.js. Core's sources already look like this and enforce it with n/file-extension-in-import, so the same three import rules are adopted here verbatim.

Two things only the built output revealed

Neither would have been caught by the test suite, because tests run against src/:

lodash — import { memoize } from 'lodash' throws at runtime under ESM: Node's lexer cannot see named exports through lodash's CJS. Switched to lodash/memoize.js, a default import of the single method. Core hit the same wall and solved it with lodash-es plus a jest moduleNameMapper; this approach needs neither.
@metamask/scure-bip39 — the deep wordlist import needed an explicit .js.

Every other CJS dependency survives named imports untouched. semver, @metamask/superstruct, @scure/base, @noble/hashes and pony-cause all have lexer friendly CJS. Verified by importing all 27 built modules individually, plus the exports map by bare specifier.

Tooling

jest.config.js and .prettierrc.js are renamed to .cjs, since "type": "module" makes bare .js files ESM. Tests still compile to CommonJS via a ts-jest transform override (matching core) with a moduleNameMapper stripping the .js specifiers back off. constraints.pro is rewritten for the single entrypoint shape.

Note

High Risk
Breaking module format and export surface affects every consumer still on CommonJS require, and lodash/mnemonic import changes can cause runtime failures if missed in downstream bundles.

Overview
Breaking: @metamask/utils is now ESM-only—require() of the package fails unless consumers use Node 22+ require(esm) or dynamic import(). main/module and dual require/import export conditions are removed; . and ./node resolve to a single ./dist/*.js with matching .d.ts types.

The build switches from ts-bridge (dual CJS/ESM artifacts) to tsc, dropping @ts-bridge/* and adding rimraf for clean builds. constraints.pro, ESLint (n/file-extension-in-import), and Jest (ts-jest CJS transform + moduleNameMapper to strip .js in tests) are aligned with MetaMask core’s ESM-only pattern.

Relative imports across src/ now use explicit .js extensions. Runtime fixes for ESM interop: hex.ts uses lodash/memoize.js instead of a named lodash import, and the @metamask/scure-bip39 wordlist deep import adds .js.

^{Reviewed by Cursor Bugbot for commit ab4c590. Bugbot is set up for automated code reviews on this repo. Configure here.}

socket-security · 2026-09-04T19:15:52Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	rimraf@5.0.10

View full report

socket-security · 2026-09-04T19:15:54Z

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

rimraf@5.0.10

View full report

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 483dd65. Configure here.}

Mrtenz · 2026-09-10T08:52:08Z

 - **BREAKING:** Drop support for Node 18 and 20 ([#328](https://github.com/MetaMask/utils/pull/328))
  - The supported range is now `^22.14.0 || ^24`, matching core.
+- **BREAKING:** The package is now ESM only ([#323](https://github.com/MetaMask/utils/pull/323))
+  - The CommonJS build is gone. `require('@metamask/utils')` now fails with `ERR_REQUIRE_ESM`; use `import` instead.


This is not accurate. Modern versions of Node.js support require(esm).

Yes thats right that was thrown in 18 which we already dropped, fixing

reworded here 4b45e57

Core is moving to an ESM only monorepo (MetaMask/core#9536), so this package should arrive already converted rather than landing as the sole hybrid one. BREAKING: the CommonJS build is gone. require('@metamask/utils') now fails with ERR_REQUIRE_ESM. `main` and `module` are removed, and both `.` and `./node` resolve through `exports` to a single ./dist/*.js with ./dist/*.d.ts types. Consumers already using `import` are unaffected. package.json adds "type": "module", collapses the dual exports map build ts-bridge -> tsc, since ts-bridge exists to emit both formats @ts-bridge/cli removed, rimraf added for build:only-clean tsconfig.build drops emitDeclarationOnly, tsc now emits the JS too 102 relative import specifiers across 45 files gained explicit .js extensions, which ESM requires. Directories resolve to /index.js. Core's sources already look like this and enforce it with n/file-extension-in-import, so the same three import rules are adopted here verbatim. Two things only surfaced by running the built output rather than the tests: lodash `import { memoize } from 'lodash'` throws at runtime under ESM, because Node's lexer cannot see named exports through lodash's CJS. Switched to `lodash/memoize.js`, a default import of the single method. Core solved the same problem by moving to lodash-es plus a jest moduleNameMapper; this needs neither. scure-bip39 the deep wordlist import needed an explicit .js. Every other CJS dependency survives named imports untouched: semver, superstruct, @scure/base, @noble/hashes and pony-cause all have lexer friendly CJS. Verified by importing all 27 built modules individually. jest.config.js and .prettierrc.js are renamed to .cjs, since "type": "module" makes bare .js ESM. Tests still compile to CommonJS through a ts-jest transform override, matching core, with a moduleNameMapper stripping the .js specifiers back off. constraints.pro is rewritten for the single entrypoint shape.

test:source runs `jest && jest-it-up`, and jest-it-up defaults to looking for jest.config.js, which is now jest.config.cjs. It supports --config, so point it there. Caught by CI rather than locally: I had been running `yarn jest` directly to work around a broken watchman on this machine, which skipped jest-it-up entirely, so test:source was never actually exercised.

cryptodev-2s · 2026-09-10T11:29:02Z

@SocketSecurity ignore npm/rimraf@5.0.10

cryptodev-2s mentioned this pull request Sep 4, 2026

feat!: drop support for Node 18 and 20 #324

Merged

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch 2 times, most recently from 0504ee1 to a2d5883 Compare September 7, 2026 12:31

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch 2 times, most recently from a7b0926 to a2d5883 Compare September 8, 2026 17:00

cryptodev-2s mentioned this pull request Sep 8, 2026

feat!: drop support for Node 18 and 20 #328

Open

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from a2d5883 to 0067215 Compare September 8, 2026 18:50

cryptodev-2s changed the base branch from migrate/pr2h-fix-tsd to migrate/drop-node-18-20 September 8, 2026 18:52

cryptodev-2s removed this pull request from stack #329 September 9, 2026 11:46

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from 0067215 to f80e63f Compare September 9, 2026 11:46

cryptodev-2s added this pull request to stack #331 September 9, 2026 11:47

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from f80e63f to 5d24967 Compare September 9, 2026 16:09

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from 5d24967 to 483dd65 Compare September 9, 2026 16:10

cursor Bot reviewed Sep 9, 2026

View reviewed changes

Comment thread package.json

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from 483dd65 to 73194e8 Compare September 9, 2026 16:32

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch 2 times, most recently from 7742fac to ccfbfb6 Compare September 9, 2026 19:23

Mrtenz reviewed Sep 10, 2026

View reviewed changes

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from 4b45e57 to 88435d0 Compare September 10, 2026 09:32

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from 88435d0 to ed955af Compare September 10, 2026 10:15

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from ed955af to 4b00bd6 Compare September 10, 2026 10:28

cryptodev-2s added 3 commits September 10, 2026 12:37

docs: correct the ESM changelog entry about require()

af16832

cryptodev-2s removed this pull request from stack #331 September 10, 2026 10:40

cryptodev-2s force-pushed the migrate/pr2i-esm-only branch from 4b00bd6 to af16832 Compare September 10, 2026 10:41

cryptodev-2s added this pull request to stack #335 September 10, 2026 10:41

cryptodev-2s mentioned this pull request Sep 10, 2026

chore: bump @ts-bridge/cli to v0.6.4 and drop unused shims #320

Closed

cryptodev-2s requested a review from Mrtenz September 10, 2026 10:46

Mrtenz reviewed Sep 10, 2026

View reviewed changes

Comment thread CHANGELOG.md Outdated

docs: update changelog use drop instead of referencing esm

ab4c590

cryptodev-2s requested a review from Mrtenz September 10, 2026 11:04

Mrtenz approved these changes Sep 10, 2026

View reviewed changes

Navigation Menu

Uh oh!

Uh oh!

feat!: convert the package to ESM only - #323

feat!: convert the package to ESM only#323
cryptodev-2s wants to merge 4 commits into
migrate/drop-node-18-20from
migrate/pr2i-esm-only

cryptodev-2s commented Sep 4, 2026 •

edited by cursor Bot

Loading

Uh oh!

socket-security Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Mrtenz Sep 10, 2026

Uh oh!

cryptodev-2s Sep 10, 2026 •

edited

Loading

Uh oh!

cryptodev-2s Sep 10, 2026

Uh oh!

Uh oh!

cryptodev-2s commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

cryptodev-2s commented Sep 4, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking

Import specifiers

Two things only the built output revealed

Tooling

Uh oh!

socket-security Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Mrtenz Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

cryptodev-2s Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cryptodev-2s Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cryptodev-2s commented Sep 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cryptodev-2s commented Sep 4, 2026 •

edited by cursor Bot

Loading

socket-security Bot commented Sep 4, 2026 •

edited

Loading

socket-security Bot commented Sep 4, 2026 •

edited

Loading

cryptodev-2s Sep 10, 2026 •

edited

Loading