chore: target Node 22 LTS (drop EOL Node 18) + required compat fixes

rhyslbw · claude · rhyslbw · commit 02ba5020daaf · 2026-06-20T06:41:32.000+01:00
The project was pinned to the now-EOL Node 18.12.0 (.nvmrc + all CI workflows)
with a stale `engines: &gt;=16.20.2`. Move to the Node 22 LTS line, tracked by
major so it doesn't go stale again:

- .nvmrc: 22 · all 9 CI workflows: node-version 22 · engines.node: &gt;=22 (all manifests)
- @types/node: ^18 -&gt; ^22

Node 22 / @types/node 22 compatibility fixes (folded in so every commit builds):
- cardano-services WsServer + projection/e2e tests: type interval handles as
  NodeJS.Timeout (setInterval no longer returns the legacy NodeJS.Timer)
- e2e measurement-util (src + test): PerformanceEntry no longer carries `detail`
- shared jest base config: fakeTimers `doNotFake: ['performance']` (Node 22's
  read-only global `performance` can't be replaced by the fake-timers impl), and
  a setupFile disabling http(s).globalAgent keepAlive — Node 19+ defaults it to
  true, so HTTP tests that restart servers between cases reused stale sockets
  ("socket hang up" / AxiosError in HttpProvider + TxSubmit suites)
- cardano-services-client test: --runInBand (avoids a jest-worker circular-JSON
  IPC crash on a follow-redirects object)
- TypeormStakePoolProvider util test: assert toThrow(SyntaxError) (V8 JSON
  message wording differs across Node versions)

Docker: NODEJS_MAJOR_VERSION=22, plus a multi-stage `deps-builder` that installs
the build toolchain (build-essential/python3/libudev-dev/libusb/pkg-config) to
compile native modules — Node 22 has no prebuilds for some older native deps
(cpu-features, chacha-native, node-hid/usb). Toolchain stays in the builder;
runtime images copy the compiled node_modules and stay lean.

Unblocks the Node-20+ dependency majors that couldn't pass CI on Node 18.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/continuous-integration-blockfrost-e2e.yaml b/.github/workflows/continuous-integration-blockfrost-e2e.yaml
@@ -51,7 +51,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
 
       - name: 🔨 Install
         uses: ./.github/actions/install
diff --git a/.github/workflows/continuous-integration-e2e.yaml b/.github/workflows/continuous-integration-e2e.yaml
@@ -51,7 +51,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
 
       - name: 🔨 Install
         uses: ./.github/actions/install
diff --git a/.github/workflows/continuous-integration-side-tests.yaml b/.github/workflows/continuous-integration-side-tests.yaml
@@ -23,7 +23,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
 
       - name: 🔨 Install
         uses: ./.github/actions/install
diff --git a/.github/workflows/continuous-integration-unit-tests.yaml b/.github/workflows/continuous-integration-unit-tests.yaml
@@ -23,7 +23,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
 
       - name: 🔨 Install
         uses: ./.github/actions/install
diff --git a/.github/workflows/k6-wallets.yaml b/.github/workflows/k6-wallets.yaml
@@ -66,7 +66,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
       - name: 🔨 Install
         uses: ./.github/actions/install
         with:
diff --git a/.github/workflows/k6-web-socket.yaml b/.github/workflows/k6-web-socket.yaml
@@ -58,7 +58,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
       - name: 🔨 Install
         uses: ./.github/actions/install
         with:
diff --git a/.github/workflows/post_integration.yml b/.github/workflows/post_integration.yml
@@ -15,7 +15,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
 
       - name: 🔨 Install
         uses: ./.github/actions/install
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -21,7 +21,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 18.12.0
+          node-version: 22
           registry-url: 'https://registry.npmjs.org'
 
       - name: Import bot's GPG key for signing commits
diff --git a/.github/workflows/test-deploy-e2e.yaml b/.github/workflows/test-deploy-e2e.yaml
@@ -63,7 +63,7 @@ jobs:
       - name: 🧰 Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 18.12.0
+          node-version: 22
 
       - name: 🔨 Install
         uses: ./.github/actions/install
diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-v18.12.0
+22
diff --git a/Dockerfile b/Dockerfile
@@ -1,7 +1,7 @@
 ARG UBUNTU_VERSION=22.04
 
 FROM ubuntu:${UBUNTU_VERSION} AS ubuntu-nodejs
-ARG NODEJS_MAJOR_VERSION=18
+ARG NODEJS_MAJOR_VERSION=22
 ENV DEBIAN_FRONTEND=nonintercative
 
 RUN \
@@ -16,16 +16,18 @@ RUN \
   apt-get install nodejs -y &&\
   apt-get install -y --no-install-recommends ca-certificates jq postgresql-client
 
-FROM ubuntu-nodejs AS cardano-services
-
-ARG NETWORK=mainnet
-ENV NETWORK=${NETWORK}
-
+# Build stage: installs the toolchain needed to compile native modules from source.
+# Node 22 has no prebuilt binaries for some of our (older) native deps
+# (cpu-features, chacha-native, node-hid/usb), so node-gyp must compile them — which
+# needs build-essential/python3 plus libudev/libusb/pkg-config for the HID/USB modules.
+# This toolchain is confined to the builder and never ships in the runtime images.
+FROM ubuntu-nodejs AS deps-builder
 RUN \
   curl --proto '=https' --tlsv1.2 -sSf -L https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - &&\
   echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list &&\
-  apt-get update && apt-get install yarn -y
-COPY packages/cardano-services/config/network/${NETWORK} /config/
+  apt-get update &&\
+  apt-get install -y yarn &&\
+  apt-get install -y --no-install-recommends build-essential python3 libudev-dev libusb-1.0-0-dev pkg-config
 WORKDIR /app
 COPY build build
 COPY packages/cardano-services/package.json packages/cardano-services/package.json
@@ -54,6 +56,21 @@ COPY .yarn .yarn
 COPY .eslintrc.js .prettierrc .yarnrc.yml complete.eslintrc.js eslint.tsconfig.json package.json tsconfig.json yarn.lock ./
 RUN yarn workspaces focus --all --production
 
+FROM ubuntu-nodejs AS cardano-services
+
+ARG NETWORK=mainnet
+ENV NETWORK=${NETWORK}
+
+RUN \
+  curl --proto '=https' --tlsv1.2 -sSf -L https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - &&\
+  echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list &&\
+  apt-get update && apt-get install yarn -y
+COPY packages/cardano-services/config/network/${NETWORK} /config/
+WORKDIR /app
+# Bring in the production install (with compiled native modules) from the builder.
+# Same base image / Node version / arch, so the compiled .node addons are compatible.
+COPY --from=deps-builder /app /app
+
 FROM cardano-services AS provider-server
 WORKDIR /app/packages/cardano-services
 HEALTHCHECK --interval=15s --timeout=15s CMD curl --fail --silent http://0.0.0.0:3000/health | jq '.ok' | awk '{ if ($0 == "true") exit 0; else exit 1}' || exit 1
diff --git a/README.md b/README.md
@@ -34,8 +34,7 @@ A suite of TypeScript packages suitable for both Node.js and browser-based devel
 
 Packages are distributed as both CommonJS and ESM modules.
 
-- Node.js >=16.20.2
-  - using with `type="module"` requires `--experimental-specifier-resolution=node` flag
+- Node.js >=22
 - Browser via bundlers (see [example webpack config](./packages/e2e/test/web-extension/webpack.config.js))
 
 ### Getting Started
@@ -69,7 +68,7 @@ A Yarn Workspace maintaining a single version across all packages.
 
 - [nvm](https://github.com/nvm-sh/nvm)
 - [yarn](https://yarnpkg.com/getting-started/install)
-- [Node.js](https://nodejs.org/en/download) 16 or later
+- [Node.js](https://nodejs.org/en/download) 22 or later
 - [Docker Desktop] 3.4 or later or a Docker installation that includes Compose V2
 
 #### Clone
diff --git a/package.json b/package.json
@@ -4,7 +4,7 @@
   "private": true,
   "description": "An SDK for interacting with the Cardano blockchain",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "workspaces": [
     "packages/*"
@@ -61,7 +61,7 @@
     "@lerna-lite/cli": "^2.1.0",
     "@lerna-lite/publish": "^2.1.0",
     "@types/jest": "^26.0.24",
-    "@types/node": "^18.11.8",
+    "@types/node": "^22",
     "@typescript-eslint/eslint-plugin": "^5.27.1",
     "@typescript-eslint/parser": "^5.27.1",
     "conventional-changelog-conventionalcommits": "^5.0.0",
diff --git a/packages/cardano-services-client/package.json b/packages/cardano-services-client/package.json
@@ -3,7 +3,7 @@
   "version": "0.26.34",
   "description": "Cardano Services Client",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -31,7 +31,7 @@
     "cleanup": "rm -rf dist node_modules",
     "lint": "eslint -c ../../complete.eslintrc.js \"src/**/*.ts\" \"test/**/*.ts\"",
     "lint:fix": "yarn lint --fix",
-    "test": "yarn build:version && jest -c ./jest.config.js",
+    "test": "yarn build:version && jest -c ./jest.config.js --runInBand",
     "test:build:verify": "tsc --build ./test",
     "test:e2e": "echo 'test:e2e' command not implemented yet",
     "coverage": "yarn test --coverage || true",
diff --git a/packages/cardano-services/package.json b/packages/cardano-services/package.json
@@ -3,7 +3,7 @@
   "version": "0.35.36",
   "description": "Cardano GraphQL Services",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/cardano-services/src/WsServer/server.ts b/packages/cardano-services/src/WsServer/server.ts
@@ -88,15 +88,15 @@ export class CardanoWsServer extends WsProvider {
   private closeNotify = noop;
   private closing = false;
   private db: Pool;
-  private heartbeatInterval: NodeJS.Timer | undefined;
+  private heartbeatInterval: NodeJS.Timeout | undefined;
   private lastReceivedNotification = 0;
   private lastSentNotification = 0;
   private lastSlot = Number.POSITIVE_INFINITY as Cardano.Slot;
   private logger: Logger;
   private networkInfo: NetworkInfoResponses;
   private notifications = new Map<number, NotificationBody>();
   private server: Server;
-  private stakeInterval: NodeJS.Timer | undefined;
+  private stakeInterval: NodeJS.Timeout | undefined;
   private syncing = true;
   private wss: WebSocketServer;
 
diff --git a/packages/cardano-services/test/StakePool/TypeormStakePoolProvider/util.test.ts b/packages/cardano-services/test/StakePool/TypeormStakePoolProvider/util.test.ts
@@ -4,7 +4,8 @@ import { validateFuzzyOptions, withTextFilter } from '../../../src/StakePool/Typ
 describe('TypeormStakePoolProvider utils', () => {
   describe('validateFuzzyOptions', () => {
     it('throws if value is not a valid JSON encoded string', () =>
-      expect(() => validateFuzzyOptions('test')).toThrow('Unexpected token e in JSON at position 1'));
+      // V8's JSON.parse error message wording differs across Node versions, so match the error type.
+      expect(() => validateFuzzyOptions('test')).toThrow(SyntaxError));
     it('throws if value is not an object', () =>
       expect(() => validateFuzzyOptions('"test"')).toThrow('must be an object'));
     it('throws without threshold', () =>
diff --git a/packages/cardano-services/test/TxSubmit/TxSubmitHttpService.test.ts b/packages/cardano-services/test/TxSubmit/TxSubmitHttpService.test.ts
@@ -121,7 +121,7 @@ describe('TxSubmitHttpService', () => {
 
     describe('/health', () => {
       it('forwards the txSubmitProvider health response', async () => {
-        const res = await axios.post(`${baseUrlWithVersion}/health`, {
+        const res = await axios.post(`${baseUrlWithVersion}/health`, undefined, {
           headers: { [CONTENT_TYPE]: APPLICATION_JSON }
         });
         expect(res.status).toBe(200);
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -3,7 +3,7 @@
   "version": "0.46.14",
   "description": "Core types and libraries for Cardano",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/crypto/package.json b/packages/crypto/package.json
@@ -3,7 +3,7 @@
   "version": "0.4.6",
   "description": "Cryptographic types and functions for Cardano",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/dapp-connector/package.json b/packages/dapp-connector/package.json
@@ -3,7 +3,7 @@
   "version": "0.13.28",
   "description": "TypeScript definitions for the dApp Connector standard CIP30",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/e2e/package.json b/packages/e2e/package.json
@@ -179,7 +179,7 @@
     "webpack-merge": "^5.8.0"
   },
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
diff --git a/packages/e2e/src/measurement-util.ts b/packages/e2e/src/measurement-util.ts
@@ -102,7 +102,10 @@ export class MeasurementUtil<T extends string> {
 
     for (const measureEntry of performance
       .getEntriesByType('measure')
-      .map(({ duration, detail }) => ({ duration, target: (detail as MarkerDetail<T>).target }))
+      .map((entry) => ({
+        duration: entry.duration,
+        target: (entry as unknown as { detail: MarkerDetail<T> }).detail.target
+      }))
       .filter(({ target }) => targets?.some((t) => t === target))) {
       const data = measurementData[measureEntry.target];
       if (!data.time) {
@@ -125,8 +128,8 @@ export class MeasurementUtil<T extends string> {
     // Count all the start markers. They all have the 'target' detail added. Stop markers don't have it
     for (const targetName of performance
       .getEntriesByType('mark')
-      .map(({ detail }) => (detail as MarkerDetail<T>)?.target)
-      .filter((target) => target && targets?.some((t) => t === target))) {
+      .map((entry) => (entry as unknown as { detail?: MarkerDetail<T> }).detail?.target)
+      .filter((target): target is T => !!target && !!targets?.some((t) => t === target))) {
       measurementData[targetName].calls_count++;
     }
 
diff --git a/packages/e2e/test/measurement-util/measurement-util.test.ts b/packages/e2e/test/measurement-util/measurement-util.test.ts
@@ -19,7 +19,7 @@ jest.mock('perf_hooks', () => ({
 type measureTargets = 't1' | 't2';
 describe('MeasurementUtil', () => {
   let measurementUtil: MeasurementUtil<measureTargets>;
-  let mockData: Partial<PerformanceEntry>[];
+  let mockData: (Partial<PerformanceEntry> & { detail: { id: number; target: string } })[];
 
   beforeEach(() => {
     measurementUtil = new MeasurementUtil<measureTargets>();
diff --git a/packages/golden-test-generator/package.json b/packages/golden-test-generator/package.json
@@ -3,7 +3,7 @@
   "version": "0.8.56",
   "description": "Generate golden test files for a range of Cardano concepts",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "bin": "dist/cjs/index.js",
   "main": "dist/cjs/index.js",
diff --git a/packages/governance/package.json b/packages/governance/package.json
@@ -3,7 +3,7 @@
   "version": "0.11.30",
   "description": "Governance types and utilities for Cardano",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/hardware-ledger/package.json b/packages/hardware-ledger/package.json
@@ -3,7 +3,7 @@
   "version": "0.16.25",
   "description": "Mappings and integration with Ledger hardware",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/hardware-trezor/package.json b/packages/hardware-trezor/package.json
@@ -3,7 +3,7 @@
   "version": "0.7.35",
   "description": "Mappings and integration with Trezor hardware",
   "engines": {
-    "node": ">=16.20.1"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/input-selection/package.json b/packages/input-selection/package.json
@@ -3,7 +3,7 @@
   "version": "0.14.31",
   "description": "TypeScript definitions for input-selection (Coin Selection Algorithms for Cardano)",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/key-management/package.json b/packages/key-management/package.json
@@ -3,7 +3,7 @@
   "version": "0.29.15",
   "description": "Key management types and utilities for Cardano",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/ogmios/package.json b/packages/ogmios/package.json
@@ -3,7 +3,7 @@
   "version": "0.18.56",
   "description": "Ogmios Providers",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/projection-typeorm/package.json b/packages/projection-typeorm/package.json
@@ -3,7 +3,7 @@
   "version": "0.10.17",
   "description": "Project Chain Sync events into PostgreSQL via TypeORM",
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
diff --git a/packages/projection/package.json b/packages/projection/package.json
@@ -59,7 +59,7 @@
     "typescript": "^4.7.4"
   },
   "engines": {
-    "node": ">=16.20.2"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
diff --git a/packages/projection/test/bufferChainSyncEvent.test.ts b/packages/projection/test/bufferChainSyncEvent.test.ts
diff --git a/packages/tx-construction/package.json b/packages/tx-construction/package.json
diff --git a/packages/util-dev/package.json b/packages/util-dev/package.json
diff --git a/packages/util-rxjs/package.json b/packages/util-rxjs/package.json
diff --git a/packages/util/package.json b/packages/util/package.json
diff --git a/packages/wallet/package.json b/packages/wallet/package.json
diff --git a/packages/web-extension/package.json b/packages/web-extension/package.json
diff --git a/test/base.jest.config.js b/test/base.jest.config.js
diff --git a/test/disableKeepAlive.js b/test/disableKeepAlive.js
diff --git a/yarn.lock b/yarn.lock
