chore: declare one Node.js range on every Prisma 8 package

README.md

@@ -24,7 +24,7 @@
 
 ## Prerequisites
 
-- Node.js 24 or newer
+- Node.js 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer, with the npm that ships with your Node.js release (npm 10 on Node.js 22)
 - A package manager (`npm`, `pnpm`, or `yarn`)
 
 ## Getting started

docs/Supported Versions.md

@@ -8,11 +8,11 @@ See [ADR 222](./architecture%20docs/adrs/ADR%20222%20-%20Version%20support%20pol
 
 | Runtime | Minimum version |
 |---|---|
-| Node.js | 24 |
+| Node.js | 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer |
 | Bun | 1.2 |
 | Deno | 2.0 |
 
-Node.js is the primary supported runtime. Bun and Deno are supported on a best-effort basis; if you encounter a Bun- or Deno-specific issue, please file an issue and include your runtime version.
+Use the npm that ships with your Node.js release (npm 10 on Node.js 22). Every published package declares this range as `engines.node`: `^22.18.0 || ^24.11.0 || >=26.0.0`. [ADR 269](./architecture%20docs/adrs/ADR%20269%20-%20One%20Node.js%20range%20for%20every%20Prisma%208%20tool.md) records why. Node.js is the primary supported runtime. Bun and Deno are supported on a best-effort basis; if you encounter a Bun- or Deno-specific issue, please file an issue and include your runtime version.
 
 ## Database servers
 

docs/architecture docs/ADR-INDEX.md

@@ -170,6 +170,7 @@ This document provides a comprehensive index of all Architectural Decision Recor
 | 216 | CLI telemetry installation ID is a stored random UUID, not a system fingerprint | Adopts a stored v4 UUID under the user's config dir as the MAU dedup key; rejects MAC-hash, machine-id, IORegistry UUID, and Windows MachineGuid alternatives on trust, regulatory, and reset-symmetry grounds | [ADR 216 - CLI telemetry installation ID is a stored random UUID not a system fingerprint.md](adrs/ADR%20216%20-%20CLI%20telemetry%20installation%20ID%20is%20a%20stored%20random%20UUID%20not%20a%20system%20fingerprint.md) |
 | 217 | CLI telemetry runs in a detached subprocess spawned at command start | Forks the telemetry sender via `child_process.fork()` at command start (not exit); parent disconnects and unrefs immediately; child owns all I/O and swallows all errors; satisfies the strict isolation contract by construction rather than diligence | [ADR 217 - CLI telemetry runs in a detached subprocess spawned at command start.md](adrs/ADR%20217%20-%20CLI%20telemetry%20runs%20in%20a%20detached%20subprocess%20spawned%20at%20command%20start.md) |
 | 242 | Public npm surface: single `@prisma` scope with consolidated publish packages | The public surface is 17 `@prisma/*` packages — database facades, extension packs, framework/toolchain, families, targets — plus the `prisma` bin shim, all under `packages/9-public/`; every other workspace package is private and reaches npm only as a subpath entrypoint of a published shell (one module, one package, preserving registry/`instanceof` identity); framework runtime and tooling publish separately for serverless bundle weight; rejects a second `@prisma-orm` scope | [ADR 242 - Public npm surface - single @prisma scope with consolidated publish packages.md](adrs/ADR%20242%20-%20Public%20npm%20surface%20-%20single%20%40prisma%20scope%20with%20consolidated%20publish%20packages.md) |
+| 269 | One Node.js range for every Prisma 8 tool | Amends ADR 222: every Prisma 8 package declares `engines.node` `^22.18.0 \|\| ^24.11.0 \|\| >=26.0.0` (Node.js 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer), the range every Prisma 8 tool is to declare (`create-prisma` already does; prisma/prisma-cli#343 and prisma/composer#351 align the `prisma` CLI and Composer); in this repository `NODE_ENGINES_RANGE` in `scripts/validate-node-engines.mjs` is the source of truth and `pnpm lint:manifests` checks it | [ADR 269 - One Node.js range for every Prisma 8 tool.md](adrs/ADR%20269%20-%20One%20Node.js%20range%20for%20every%20Prisma%208%20tool.md) |
 
 ## No-Emit Workflow
 

docs/architecture docs/adrs/ADR 222 - Version support policy.md

@@ -1,6 +1,6 @@
 # ADR 222 — Version support policy for Prisma Next
 
-**Status:** Accepted — PostgreSQL floor amended by [ADR 248](ADR%20248%20-%20PostgreSQL%20floor%20lowered%20to%2015.md)
+**Status:** Accepted — PostgreSQL floor amended by [ADR 248](ADR%20248%20-%20PostgreSQL%20floor%20lowered%20to%2015.md); Node.js range amended by [ADR 269](ADR%20269%20-%20One%20Node.js%20range%20for%20every%20Prisma%208%20tool.md)
 **Date:** 2026-05-31
 **Linear:** TML-1810, TML-1809
 
@@ -14,7 +14,7 @@ The ratified floor table:
 
 | Dimension | Floor | Enforcement |
 |---|---|---|
-| Node.js | `>=24` | `engines.node` on every publishable package |
+| Node.js | `^22.18.0 \|\| ^24.11.0 \|\| >=26.0.0` (changed from `>=24` by [ADR 269](ADR%20269%20-%20One%20Node.js%20range%20for%20every%20Prisma%208%20tool.md)) | `engines.node` on every publishable package + source-of-truth constant + drift check |
 | TypeScript | `>=5.9` | optional `peerDependencies.typescript` on every publishable package + source-of-truth constant + drift test |
 | PostgreSQL (server) | `15` (lowered from `17` by [ADR 248](ADR%20248%20-%20PostgreSQL%20floor%20lowered%20to%2015.md)) | `prismaNext.minServerVersion` on `@internal/target-postgres` + CLI mirror + `postgres:15` CI service containers + `docker-compose.yaml` |
 | MongoDB (server) | `8.0` | `prismaNext.minServerVersion` on `@internal/target-mongo` + CLI mirror; MMS 11.x downloads 8.2.x by default |
@@ -38,7 +38,7 @@ The guiding insight: **lowering a floor is backwards-compatible; raising one is
 
 ## Why these specific floors
 
-**Node.js 24**: This is the current Active LTS line. Node 22 reached LTS in October 2024; Node 24 is the successor, released April 2025. `tsdown` infers the JS output target from `engines.node`, so the declaration is load-bearing, not advisory: packages with `>=20` would produce wider-compat output than the codebase actually requires or tests.
+**Node.js 24**: [ADR 269](ADR%20269%20-%20One%20Node.js%20range%20for%20every%20Prisma%208%20tool.md) replaced this floor with the range `^22.18.0 || ^24.11.0 || >=26.0.0`, shared by every Prisma 8 tool. The original reasoning follows. This is the current Active LTS line. Node 22 reached LTS in October 2024; Node 24 is the successor, released April 2025. `tsdown` infers the JS output target from `engines.node`, so the declaration is load-bearing, not advisory: packages with `>=20` would produce wider-compat output than the codebase actually requires or tests.
 
 **TypeScript 5.9**: The latest GA release at the time this policy was ratified, and the version pinned in the workspace catalog. TypeScript peer declarations are optional because TypeScript is a dev-time tool — plain-JS consumers must not be forced to install it. The optional peer allows type-checking consumers to get type information without requiring it universally.
 
@@ -54,7 +54,7 @@ The guiding insight: **lowering a floor is backwards-compatible; raising one is
 
 ### Node.js engines
 
-Every publishable package declares `"engines": { "node": ">=24" }`. This is enforced structurally: `tsdown` uses the `engines.node` field to set its output target, so a package that omits or understates this will produce different (and potentially unintended) JavaScript output.
+Every publishable package declares `"engines": { "node": "^22.18.0 || ^24.11.0 || >=26.0.0" }` ([ADR 269](ADR%20269%20-%20One%20Node.js%20range%20for%20every%20Prisma%208%20tool.md)). The source of truth is `NODE_ENGINES_RANGE` in `scripts/validate-node-engines.mjs`, and `pnpm lint:manifests` checks every package against it. This is enforced structurally: `tsdown` uses the `engines.node` field to set its output target, so a package that omits or understates this will produce different (and potentially unintended) JavaScript output.
 
 ### TypeScript peer
 

docs/architecture docs/adrs/ADR 269 - One Node.js range for every Prisma 8 tool.md

@@ -0,0 +1,51 @@
+# ADR 269 — One Node.js range for every Prisma 8 tool
+
+**Status:** Accepted
+**Date:** 2026-10-09
+**Amends:** [ADR 222 — Version support policy](ADR%20222%20-%20Version%20support%20policy.md)
+
+---
+
+## Decision
+
+Every Prisma 8 package declares this `engines.node` range:
+
+```json
+"engines": { "node": "^22.18.0 || ^24.11.0 || >=26.0.0" }
+```
+
+In prose: Node.js 22.18 or newer on the 22 line, 24.11 or newer on the 24 line, or 26 or newer, each with the npm that ships with that Node.js release (npm 10 on Node.js 22).
+
+The same range applies to every Prisma 8 tool: the `@prisma/orm-*` packages in this repository, the `prisma` CLI, Composer, `create-prisma`, and the projects `create-prisma` generates. A user who meets the requirement of one tool meets the requirement of all of them.
+
+## Why one range
+
+A user meets the Prisma 8 tools one after another: `create-prisma` scaffolds a project, the project installs `@prisma/orm-postgres`, and the user runs the `prisma` CLI. When each tool states a different Node.js requirement, the user finds out which one is strictest only when an install warns or a command fails. One range removes that.
+
+## Why these versions
+
+- **22.18** is the first Node.js 22 release that runs `.ts` files without a flag. Users run `node migration.ts` to emit a migration, so a Node.js version that cannot run `.ts` files cannot use Prisma 8 migrations.
+- **24.11** is the first Long Term Support release of Node.js 24.
+- **26 or newer** covers current and future releases.
+
+## Enforcement
+
+- `NODE_ENGINES_RANGE` in `scripts/validate-node-engines.mjs` is the source of truth. `pnpm lint:manifests` fails when a publishable package lacks `engines.node`, or when any package under `packages/` declares a different range. The check covers only `packages/`.
+- `tsdown` derives each package's build target from `engines.node`, so every package builds for `node22.18.0`, the lowest version in the range.
+- The examples under `examples/` are applications. They declare the same range unless a framework they use needs a narrower one; `examples/react-router-demo` declares `^22.22.0 || ^24.11.0 || >=26.0.0` because React Router needs Node.js 22.22 or newer.
+- The scaffold READMEs that `prisma orm init` writes, the repository README, and [Supported Versions](../../Supported%20Versions.md) state the range in prose.
+
+The repository's own development toolchain is separate: the root `package.json` and `.tool-versions` choose the Node.js version contributors and CI use, and this ADR does not change them.
+
+## Consequences
+
+- Node.js 22.18 and newer 22.x releases become supported.
+- This ADR overrides ADR 222's rule that a declared floor must never claim more than this repository's test infrastructure exercises, for Node.js only. The Node.js range is a product decision shared by every Prisma 8 tool, and the team decided not to add CI jobs for it. This repository's CI runs the test suites on the Node.js version in `.tool-versions` (a 24.x release) only. What exercises the rest of the range today:
+  - Node.js 22.18.0: `pnpm build` and `pnpm test:packages` passed on it when this ADR was written. The nightly getting-started check in prisma/getting-started-eval runs on Node.js 22.18.0 with its own npm, and installs and runs Prisma ORM through `create-prisma` every night.
+  - Node.js 26: nothing tests it yet. A change that breaks it would go unnoticed until a user reports it.
+- `tsdown` lowers syntax to Node.js 22.18. It does not check built-in APIs: code must not call an API newer than Node.js 22.18, and only a test run on Node.js 22.18 catches one that does.
+
+## Alternatives considered
+
+- **Keep `>=24`.** This excludes users on Node.js 22, which is still a supported Long Term Support line, and it differs from the range `create-prisma` already declares.
+- **A range per tool.** Each tool could state only what it needs. Users would then have to meet the strictest requirement across several tools without being told which one it is.

examples/bundle-size/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "version": "8.0.0-rc.17",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "start:pg": "tsx src/postgres/main.ts",

examples/mongo-blog-leaderboard/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

examples/mongo-demo/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

examples/multi-extension-monorepo/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "description": "Worked example: monorepo with two internal contract-space packages and an aggregating app. Exercises the framework's per-space planner/runner/verifier with multiple extensions in one application.",
   "scripts": {

examples/paradedb-demo/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

examples/prisma-8-cloudflare-worker/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

examples/prisma-8-demo-sqlite/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

examples/prisma-8-demo/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "dev": "vite",

examples/prisma-8-postgis-demo/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

examples/prisma7-adoption/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "db:start": "tsx scripts/db-start.ts",

examples/react-router-demo/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.22.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "dev": "react-router dev",

examples/retail-store/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

examples/supabase/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "scripts": {
     "emit": "prisma contract emit",

package.json

@@ -45,9 +45,9 @@
     "rules:sync": "node scripts/sync-agent-rules.mjs",
     "rules:footprint": "node scripts/rules-footprint.mjs",
     "lint:docs": "node scripts/validate-package-readmes.mjs",
-    "lint:manifests": "node scripts/validate-package-manifests.mjs && node scripts/validate-typescript-peer.mjs",
+    "lint:manifests": "node scripts/validate-package-manifests.mjs && node scripts/validate-typescript-peer.mjs && node scripts/validate-node-engines.mjs",
     "lint:workflows": "node scripts/lint-workflow-triggers.mjs",
-    "test:scripts": "node --test scripts/coverage-config.test.mjs scripts/coverage-report.test.mjs scripts/lint-workflow-triggers.test.mjs scripts/upgrade-coverage-workflows.test.mjs scripts/validate-skills.test.mjs scripts/determine-version-utils.test.ts scripts/check-upgrade-coverage.test.mjs scripts/check-release-notes.test.mjs scripts/set-version-utils.test.ts scripts/check-publish-deps.test.mjs scripts/check-conformance.test.mjs scripts/check-publish-deps-pn-pins.test.mjs scripts/check-publish-deps-declarations.test.mjs scripts/validate-package-manifests.test.mjs scripts/validate-package-readmes.test.mjs scripts/publish-packages-utils.test.mjs scripts/check-clean-tree.test.mjs scripts/lint-casts.test.mjs scripts/lint-throws.test.mjs scripts/list-error-codes.test.mjs scripts/lint-framework-vocabulary.test.mjs scripts/lint-single-import-root.test.mjs scripts/lint-legacy-name.test.mjs scripts/lint-vitest-timeouts.test.mjs scripts/lint-consumer-internal-imports.test.mjs scripts/sync-agent-rules.test.mjs scripts/validate-typescript-peer.test.mjs scripts/run-logged.test.mjs scripts/migrate-migrations-layout.test.mjs scripts/codemods/add-model-map.test.mjs scripts/codemods/rewrite-sql-strings.test.mjs skills-contrib/review-fetch-phase/scripts/guard-review-artifacts-ignored.test.mjs skills-contrib/review-fetch-phase/scripts/render-review-state.test.mjs skills-contrib/review-triage-phase/scripts/render-review-actions.test.mjs",
+    "test:scripts": "node --test scripts/coverage-config.test.mjs scripts/coverage-report.test.mjs scripts/lint-workflow-triggers.test.mjs scripts/upgrade-coverage-workflows.test.mjs scripts/validate-skills.test.mjs scripts/determine-version-utils.test.ts scripts/check-upgrade-coverage.test.mjs scripts/check-release-notes.test.mjs scripts/set-version-utils.test.ts scripts/check-publish-deps.test.mjs scripts/check-conformance.test.mjs scripts/check-publish-deps-pn-pins.test.mjs scripts/check-publish-deps-declarations.test.mjs scripts/validate-package-manifests.test.mjs scripts/validate-package-readmes.test.mjs scripts/publish-packages-utils.test.mjs scripts/check-clean-tree.test.mjs scripts/lint-casts.test.mjs scripts/lint-throws.test.mjs scripts/list-error-codes.test.mjs scripts/lint-framework-vocabulary.test.mjs scripts/lint-single-import-root.test.mjs scripts/lint-legacy-name.test.mjs scripts/lint-vitest-timeouts.test.mjs scripts/lint-consumer-internal-imports.test.mjs scripts/sync-agent-rules.test.mjs scripts/validate-typescript-peer.test.mjs scripts/validate-node-engines.test.mjs scripts/run-logged.test.mjs scripts/migrate-migrations-layout.test.mjs scripts/codemods/add-model-map.test.mjs scripts/codemods/rewrite-sql-strings.test.mjs skills-contrib/review-fetch-phase/scripts/guard-review-artifacts-ignored.test.mjs skills-contrib/review-fetch-phase/scripts/render-review-state.test.mjs skills-contrib/review-triage-phase/scripts/render-review-actions.test.mjs",
     "bump-version": "node scripts/bump-version.ts",
     "check:publish-deps": "node scripts/check-publish-deps.mjs",
     "check:conformance": "node scripts/check-conformance.mjs",

packages/0-config/tsdown/README.md

@@ -12,7 +12,7 @@ Your package needs to have:
 
 1. `tsconfig.prod.json` - a TypeScript configuration file specific for bundling.
 
-2. `package.json#engines.node` - `tsdown` infers the bundling target based on this value. e.g. `{ "engines": { "node": ">=24" } }`
+2. `package.json#engines.node` - `tsdown` infers the bundling target based on this value. e.g. `{ "engines": { "node": "^22.18.0 || ^24.11.0 || >=26.0.0" } }`
 
 3. `"tsdown": "catalog:"` in your packages `devDependencies`.
 

packages/0-shared/extension-author-tools/package.json

@@ -20,7 +20,7 @@
     "bin"
   ],
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/0-shared/publish-surface/package.json

@@ -39,7 +39,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/1-framework/0-foundation/contract/package.json

@@ -54,7 +54,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/1-framework/0-foundation/utils/package.json

@@ -53,7 +53,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/1-framework/1-core/config/package.json

@@ -47,7 +47,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/1-framework/1-core/errors/package.json

@@ -45,7 +45,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/1-framework/1-core/framework-components/package.json

@@ -54,7 +54,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/1-framework/1-core/operations/package.json

@@ -44,7 +44,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",

packages/1-framework/1-core/ts-render/package.json

@@ -43,7 +43,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^22.18.0 || ^24.11.0 || >=26.0.0"
   },
   "repository": {
     "type": "git",