chore: drop Node 20, target ES2022 and build packages as ESM-only

.github/workflows/lint-build-test.yml

@@ -89,7 +89,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.x, 22.x, 24.x]
+        node-version: [22.x, 24.x]
     outputs:
       child-workspace-package-names: ${{ steps.workspace-package-names.outputs.child-workspace-package-names }}
     steps:
@@ -213,7 +213,7 @@ jobs:
     needs: [prepare, build]
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [22.x, 24.x]
         package-name: ${{ fromJson(needs.prepare.outputs.child-workspace-package-names) }}
     steps:
       - name: Checkout and setup environment

.yarnrc.yml

@@ -27,7 +27,6 @@ npmPreapprovedPackages:
   - "@metamask/*"
   - "@metamask-previews/*"
   - "@lavamoat/*"
-  - "@ts-bridge/*"
 
 plugins:
   - path: .yarn/plugins/@yarnpkg/plugin-allow-scripts.cjs

AGENTS.md

@@ -51,12 +51,12 @@ The monorepo uses a hierarchical configuration approach for different tools. For
 - `tsconfig.packages.json` defines shared TypeScript settings for all packages.
 - Packages are either Snaps or non-Snaps:
   - `tsconfig.packages.snaps.json` defines shared TypeScript settings for all Snap packages.
-  - `tsconfig.packages.libs.build.json` defines shared declaration build settings for library packages, used by `ts-bridge`.
+  - `tsconfig.packages.libs.build.json` defines shared build settings for library packages, used by `tsc --build`.
 - `tsconfig.scripts.json` defines shared TypeScript settings for directories in `scripts/`.
 - The root `lint:tsc` script checks repository scripts with `tsconfig.json`, then checks each
   workspace package configuration directly. It does not build Snap bundles with `tsc`.
 - `packages/**/tsconfig.json` (and `scripts/create-package/library-template/tsconfig.json`) defines TypeScript settings for each package that are meant to be used by code editors and type checking.
-- Library packages and the library template also have `tsconfig.build.json` files for `ts-bridge` declaration builds. Snap packages do not have build configs because `mm-snap` builds their bundles.
+- Library packages and the library template also have `tsconfig.build.json` files for ESM-only `tsc` builds. Snap packages do not have build configs because `mm-snap` builds their bundles.
 - `scripts/create-package/tsconfig.json` customizes TypeScript settings for the `create-package` tool.
 
 #### Jest

docs/processes/adding-new-packages.md

@@ -8,7 +8,7 @@ Manually creating a new monorepo package can be a tedious, even frustrating proc
 1. Create a new package using `yarn create-package`.
    - You can specify the kind of package you want with the `--type` option. It defaults to `snap`:
      - `--type snap` creates a new Snap, whose bundle is built with `mm-snap`.
-     - `--type library` (or the `--type lib` shorthand) creates a new non-Snap package, whose declarations are built with `ts-bridge`.
+     - `--type library` (or the `--type lib` shorthand) creates a new non-Snap package, which is built as ESM-only with `tsc`.
    - Use the `--help` flag for usage information.
    - Once this is done, you can find a package with your chosen name in `/packages`.
 2. Make sure your license is correct.

jest.config.packages.js

@@ -90,6 +90,12 @@ module.exports = {
       // so in that case use their published versions
       '<rootDir>/../../node_modules/@metamask/$1',
     ],
+    // Source code uses `lodash-es` (ESM-only), but tests are compiled to
+    // CommonJS, where `lodash` is used instead.
+    '^lodash-es$': 'lodash',
+    // Sources use explicit `.js` extensions (required for Node16 ESM
+    // resolution), which Jest must map back to the `.ts` files.
+    '^(\\.{1,2}/.*)\\.js$': '$1',
   },
 
   // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader

package.json

@@ -98,7 +98,7 @@
     "ws@7.4.6": "^7.5.10"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^22.14.0 || ^24"
   },
   "packageManager": "yarn@4.17.1",
   "lavamoat": {

packages/bitcoin-wallet-snap/jest.config.mjs

@@ -35,6 +35,16 @@ const config = {
   transform: {
     '^.+\\.(t|j)sx?$': 'ts-jest',
   },
+  moduleNameMapper: {
+    // `@metamask/snap-networks-utils` is ESM-only, which Jest's CommonJS
+    // runtime cannot require, so map it to the uncompiled source instead.
+    // The source uses Node16-style `.js` specifiers and `lodash-es`, which
+    // must be mapped as well.
+    '^@metamask/snap-networks-utils$':
+      '<rootDir>/../snap-networks-utils/src/index.ts',
+    '^lodash-es$': 'lodash',
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
   resetMocks: true,
   testMatch: ['**/src/**/?(*.)+(spec|test).[tj]s?(x)'],
 };

packages/bitcoin-wallet-snap/package.json

@@ -74,6 +74,6 @@
     "wif": "^5.0.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^22.14.0 || ^24"
   }
 }

packages/snap-networks-utils/CHANGELOG.md

@@ -31,6 +31,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Require Node.js `^22.14.0 || ^24`; Node.js 20 and below are no longer supported ([#273](https://github.com/MetaMask/internal-snaps/pull/273))
+- Compile with TypeScript `target` and `lib` of `ES2022` ([#273](https://github.com/MetaMask/internal-snaps/pull/273))
+- Replace the dual CommonJS/ESM build with an ESM-only build, using `tsc` instead of `ts-bridge`. The package now ships `dist/index.js` and `dist/index.d.ts`; CommonJS consumers need Node.js 22+'s `require(esm)` support or a bundler ([#273](https://github.com/MetaMask/internal-snaps/pull/273))
 - **BREAKING** Replace the logger utilities with a configurable `Logger` class that requires a log level and supports level filtering, per-instance prefixes, and method decorators. ([#136](https://github.com/MetaMask/internal-snaps/pull/136))
 - Bump `@metamask/utils` from `^11.9.0` to `^11.11.9` ([#161](https://github.com/MetaMask/internal-snaps/pull/161))
 - **BREAKING** Bump `@metamask/snaps-sdk` from `^11.2.0` to `^12.0.1` ([#214](https://github.com/MetaMask/internal-snaps/pull/214))

scripts/create-package/library-template/jest.config.js → packages/snap-networks-utils/jest.config.cjs

@@ -4,7 +4,7 @@
  */
 
 const merge = require('deepmerge');
 const path = require('path');
 
 const baseConfig = require('../../jest.config.packages');
 
@@ -14,6 +14,21 @@
   // The display name when running multiple projects
   displayName,
 
+  // This package is an ES module (`"type": "module"`), but tests are run in
+  // CommonJS mode, so force `ts-jest` to compile to CommonJS regardless of
+  // the package type.
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          module: 'CommonJS',
+          moduleResolution: 'node10',
+        },
+      },
+    ],
+  },
+
   coveragePathIgnorePatterns: [
     ...(baseConfig.coveragePathIgnorePatterns ?? []),
     '.*/__mocks__/',

packages/snap-networks-utils/package.json

@@ -18,39 +18,20 @@
   "files": [
     "dist/"
   ],
+  "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.cjs",
-  "types": "./dist/index.d.cts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./dedupe": {
-      "import": {
-        "types": "./dist/utils/dedupe/InFlightCoalescer.d.mts",
-        "default": "./dist/utils/dedupe/InFlightCoalescer.mjs"
-      },
-      "require": {
-        "types": "./dist/utils/dedupe/InFlightCoalescer.d.cts",
-        "default": "./dist/utils/dedupe/InFlightCoalescer.cjs"
-      }
+      "types": "./dist/utils/dedupe/InFlightCoalescer.d.ts",
+      "default": "./dist/utils/dedupe/InFlightCoalescer.js"
     },
     "./logger": {
-      "import": {
-        "types": "./dist/utils/logger/Logger.d.mts",
-        "default": "./dist/utils/logger/Logger.mjs"
-      },
-      "require": {
-        "types": "./dist/utils/logger/Logger.d.cts",
-        "default": "./dist/utils/logger/Logger.cjs"
-      }
+      "types": "./dist/utils/logger/Logger.d.ts",
+      "default": "./dist/utils/logger/Logger.js"
     },
     "./package.json": "./package.json"
   },
@@ -59,8 +40,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
-    "build:all": "ts-bridge --project tsconfig.build.json --verbose --clean",
+    "build": "tsc --build --verbose tsconfig.build.json",
+    "build:clean": "tsc --build --clean tsconfig.build.json && rimraf ./dist",
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/snap-networks-utils",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/snap-networks-utils",
@@ -77,23 +58,23 @@
     "@metamask/superstruct": "^3.4.1",
     "@metamask/utils": "^11.11.0",
     "bignumber.js": "^9.3.1",
-    "lodash": "^4.17.21"
+    "lodash-es": "^4.17.21"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.1",
     "@metamask/messenger": "^2.0.0",
-    "@ts-bridge/cli": "^0.6.4",
     "@types/jest": "^30.0.0",
-    "@types/lodash": "^4.17.15",
+    "@types/lodash-es": "^4.17.12",
     "deepmerge": "^4.2.2",
     "jest": "30.0.3",
+    "rimraf": "^6.0.1",
     "ts-jest": "^29.4.1",
     "tsx": "^4.20.5",
     "typedoc": "^0.25.13",
     "typedoc-plugin-missing-exports": "^2.0.0",
     "typescript": "~5.8.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^22.14.0 || ^24"
   }
 }

packages/snap-networks-utils/src/index.ts

@@ -2,38 +2,38 @@ export {
   ASSETS_PROVIDER_NAME,
   AssetsProvider,
   type AssetsProviderMessenger,
-} from './providers/assets/AssetsProvider';
+} from './providers/assets/AssetsProvider.js';
 export {
   REMOTE_FEATURE_FLAGS_PROVIDER_NAME,
   RemoteFeatureFlagsProvider,
   type RemoteFeatureFlagsProviderMessenger,
-} from './providers/remote-feature-flags/RemoteFeatureFlagsProvider';
-export { safeMerge } from './utils/safeMerge/safeMerge';
-export { buildUrl } from './utils/buildUrl/buildUrl';
-export type { BuildUrlParams } from './utils/buildUrl/buildUrl';
+} from './providers/remote-feature-flags/RemoteFeatureFlagsProvider.js';
+export { safeMerge } from './utils/safeMerge/safeMerge.js';
+export { buildUrl } from './utils/buildUrl/buildUrl.js';
+export type { BuildUrlParams } from './utils/buildUrl/buildUrl.js';
 export {
   sanitizeControlCharacters,
   sanitizeUri,
-} from './utils/sanitize/sanitize';
-export { UrlStruct } from './utils/urlStruct/urlStruct';
-export { UuidStruct } from './utils/uuidStruct/uuidStruct';
+} from './utils/sanitize/sanitize.js';
+export { UrlStruct } from './utils/urlStruct/urlStruct.js';
+export { UuidStruct } from './utils/uuidStruct/uuidStruct.js';
 export {
   batchesAll,
   batchesAllSettled,
   batchesAllSettledWithChunks,
   batchesAllWithChunks,
   chunks,
-} from './utils/async/async';
-export { Logger, LogLevel } from './utils/logger/Logger';
+} from './utils/async/async.js';
+export { Logger, LogLevel } from './utils/logger/Logger.js';
 export type {
   LoggerOptions,
   LoggerMethod,
   LogMethod,
   LogMethodDecorator,
   LoggerDecorators,
-} from './utils/logger/Logger';
-export { serialize, deserialize } from './utils/serialization/serialization';
-export type { Serializable } from './utils/serialization/types';
+} from './utils/logger/Logger.js';
+export { serialize, deserialize } from './utils/serialization/serialization.js';
+export type { Serializable } from './utils/serialization/types.js';
 export {
   parseProofOfOwnershipMessage,
   ProofOfOwnershipBatchErrorStruct,
@@ -44,7 +44,7 @@ export {
   ProofOfOwnershipBatchSuccessStruct,
   ProofOfOwnershipMessageStruct,
   PROOF_OF_OWNERSHIP_MESSAGE_PREFIX,
-} from './utils/proofOfOwnership/proofOfOwnership';
+} from './utils/proofOfOwnership/proofOfOwnership.js';
 export type {
   ProofOfOwnershipBatchError,
   ProofOfOwnershipBatchItemResponse,
@@ -53,23 +53,25 @@ export type {
   ProofOfOwnershipBatchResponse,
   ProofOfOwnershipBatchSuccess,
   ProofOfOwnershipMessage,
-} from './utils/proofOfOwnership/proofOfOwnership';
+} from './utils/proofOfOwnership/proofOfOwnership.js';
 export {
   createOriginPermissions,
   DEFAULT_PROD_ORIGINS,
   DEFAULT_DEV_ORIGINS,
   DEFAULT_METAMASK_ORIGIN,
-} from './utils/originPermissions/createOriginPermissions';
-export type { CreateOriginPermissionsParams } from './utils/originPermissions/createOriginPermissions';
-export { validateOrigin } from './utils/originPermissions/validateOrigin';
+} from './utils/originPermissions/createOriginPermissions.js';
+export type { CreateOriginPermissionsParams } from './utils/originPermissions/createOriginPermissions.js';
+export { validateOrigin } from './utils/originPermissions/validateOrigin.js';
 export {
   createSnapErrorHandling,
   createTrackError,
   createWithCatchAndThrowSnapError,
   isSnapRpcError,
   normalizeError,
-} from './utils/errors';
-export { InFlightCoalescer } from './utils/dedupe/InFlightCoalescer';
+  // Directory imports require the explicit `/index.js` under Node16 ESM resolution.
+  // eslint-disable-next-line import-x/no-useless-path-segments
+} from './utils/errors/index.js';
+export { InFlightCoalescer } from './utils/dedupe/InFlightCoalescer.js';
 export type {
   CreateSnapErrorHandlingOptions,
   CreateTrackErrorOptions,
@@ -82,4 +84,6 @@ export type {
   SnapTrackErrorRequest,
   TrackErrorCapableProvider,
   TrackErrorFn,
-} from './utils/errors';
+  // Directory imports require the explicit `/index.js` under Node16 ESM resolution.
+  // eslint-disable-next-line import-x/no-useless-path-segments
+} from './utils/errors/index.js';

packages/snap-networks-utils/src/providers/assets/AssetsProvider.test.ts

@@ -1,8 +1,8 @@
 import type { AccountId, Caip19AssetId } from '@metamask/assets-controller';
 import type { CaipChainId } from '@metamask/utils';
 
-import type { AssetsProviderMessenger } from './AssetsProvider';
-import { AssetsProvider } from './AssetsProvider';
+import type { AssetsProviderMessenger } from './AssetsProvider.js';
+import { AssetsProvider } from './AssetsProvider.js';
 
 const ACCOUNT_ID: AccountId = '550e8400-e29b-41d4-a716-446655440000';
 const ASSET_ID: Caip19AssetId = 'tron:728126428/slip44:195';

packages/snap-networks-utils/src/providers/remote-feature-flags/RemoteFeatureFlagsProvider.test.ts

@@ -1,7 +1,7 @@
 import type { RemoteFeatureFlagControllerState } from '@metamask/remote-feature-flag-controller';
 
-import type { RemoteFeatureFlagsProviderMessenger } from './RemoteFeatureFlagsProvider';
-import { RemoteFeatureFlagsProvider } from './RemoteFeatureFlagsProvider';
+import type { RemoteFeatureFlagsProviderMessenger } from './RemoteFeatureFlagsProvider.js';
+import { RemoteFeatureFlagsProvider } from './RemoteFeatureFlagsProvider.js';
 
 const FLAG_KEY_A = 'flag-a';
 const FLAG_KEY_B = 'flag-b';

packages/snap-networks-utils/src/utils/async/async.test.ts

@@ -4,7 +4,7 @@ import {
   batchesAllSettledWithChunks,
   batchesAllWithChunks,
   chunks,
-} from './async';
+} from './async.js';
 
 describe('batchesAll', () => {
   it('throws when batchSize is less than 1', async () => {

packages/snap-networks-utils/src/utils/buildUrl/buildUrl.test.ts

@@ -1,4 +1,4 @@
-import { buildUrl } from './buildUrl';
+import { buildUrl } from './buildUrl.js';
 
 describe('buildUrl', () => {
   it('builds and sanitizes URLs, including path and query parameters', () => {

packages/snap-networks-utils/src/utils/buildUrl/buildUrl.ts

@@ -1,7 +1,10 @@
 import { assert } from '@metamask/superstruct';
 
-import { sanitizeControlCharacters, sanitizeUri } from '../sanitize/sanitize';
-import { UrlStruct } from '../urlStruct/urlStruct';
+import {
+  sanitizeControlCharacters,
+  sanitizeUri,
+} from '../sanitize/sanitize.js';
+import { UrlStruct } from '../urlStruct/urlStruct.js';
 
 export type BuildUrlParams = {
   baseUrl: string;

packages/snap-networks-utils/src/utils/dedupe/InFlightCoalescer.test.ts

@@ -1,4 +1,4 @@
-import { InFlightCoalescer } from './InFlightCoalescer';
+import { InFlightCoalescer } from './InFlightCoalescer.js';
 
 describe('InFlightCoalescer', () => {
   it('returns the result of the wrapped function', async () => {

packages/snap-networks-utils/src/utils/errors/errors.test.ts

@@ -18,10 +18,10 @@ import {
   UserRejectedRequestError,
 } from '@metamask/snaps-sdk';
 
-import { mockLogger } from '../logger/__mocks__/Logger';
-import { createWithCatchAndThrowSnapError, normalizeError } from './errors';
-import type { CreateWithCatchAndThrowSnapErrorOptions } from './errors';
-import { isSnapRpcError } from './snapRpcError';
+import { mockLogger } from '../logger/__mocks__/Logger.js';
+import { createWithCatchAndThrowSnapError, normalizeError } from './errors.js';
+import type { CreateWithCatchAndThrowSnapErrorOptions } from './errors.js';
+import { isSnapRpcError } from './snapRpcError.js';
 
 type SetupTestResult = {
   trackError: jest.Mock;

packages/snap-networks-utils/src/utils/errors/errors.ts

@@ -1,8 +1,8 @@
 import { SnapError, getErrorMessage } from '@metamask/snaps-sdk';
 
-import type { Logger } from '../logger/Logger';
-import { isSnapRpcError } from './snapRpcError';
-import type { SnapRpcError } from './snapRpcError';
+import type { Logger } from '../logger/Logger.js';
+import { isSnapRpcError } from './snapRpcError.js';
+import type { SnapRpcError } from './snapRpcError.js';
 
 /**
  * Sends an error to the snap's tracking transport (e.g. `snap_trackError`).