objectstack-ai · os-zhuang · Jul 28, 2026 · Jul 28, 2026
diff --git a/.changeset/engines-node-22.md b/.changeset/engines-node-22.md
@@ -0,0 +1,54 @@
+---
+"create-objectstack": major
+"@objectstack/spec": major
+"@objectstack/cli": major
+---
+
+feat!: require Node.js 22 — promise the runtime we actually test (#3825)
+
+Every published package declared `engines.node: ">=18.0.0"`. **Node 18 reached
+end-of-life on 2025-04-30 and Node 20 on 2026-04-30**, so the compatibility
+promise covered two runtimes nobody patches — and, after #3830 moved CI to Node
+22, two runtimes nothing in this repo verifies.
+
+That left the promise and the evidence with **no overlap at all**:
+
+| | Node version |
+|---|---|
+| What CI validates every PR on | **22** |
+| What `release.yml` publishes from | **22** |
+| What every shipped Docker image runs (`docker/Dockerfile`, `blank` template, self-hosting docs) | **22** |
+| What `engines.node` promised users | **>=18** |
+
+`engines.node` is now `>=22.0.0` across all 50 manifests. This is the honest
+floor: it is the only runtime the packages are built, tested and shipped on.
+
+## Migration
+
+**If you are on Node 22 or newer, nothing changes.** Node 24 (Active LTS since
+2025-10-28) and Node 26 both satisfy the new range.
+
+If you are on Node 18 or 20, upgrade to Node 22+. Both are past end-of-life and
+receive no security patches:
+
+```bash
+nvm install 22 && nvm use 22
+```
+
+npm and pnpm surface an unsatisfied `engines` as an **`EBADENGINE` warning**, not
+a hard failure, so an existing install will not break the moment you upgrade —
+but the package is no longer tested on that runtime, and the failures are the
+kind that do not announce themselves. #3812 is the worked example: a native
+dependency whose `engines` required a newer Node loaded anyway on the older one
+and then killed the test worker at the process level, with no JS error and a
+summary that still said "passed".
+
+If your CI pins Node, pin it to 22 as well — running your gates on a runtime
+your dependencies no longer support is exactly the split this change closes.
+
+## Also updated
+
+The "Node 18+" prerequisite was restated in ten user-facing places
+(`README.md`, `CONTRIBUTING.md`, the getting-started and deployment docs, the
+todo example, and the `objectstack-platform` skill's `compatibility` field).
+All now say 22. Changelogs and ADRs are historical records and were left alone.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -22,7 +22,7 @@ We are committed to providing a welcoming and inclusive environment. Please be r
 
 ### Prerequisites
 
-- **Node.js** >= 18.0.0
+- **Node.js** >= 22.0.0
 - **PNPM** >= 8.0.0
 - **Git** >= 2.0.0
 

diff --git a/README.md b/README.md
@@ -204,7 +204,7 @@ See [Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-hosting
 ```bash
 git clone https://github.com/objectstack-ai/objectstack.git
 cd objectstack
-pnpm install # Node 18+, pnpm 8+ (corepack enable)
+pnpm install # Node 22+, pnpm 8+ (corepack enable)
 pnpm build # build all packages
 pnpm dev # run the showcase example (REST + Console on :3000)
 ```

diff --git a/apps/docs/package.json b/apps/docs/package.json
@@ -40,6 +40,6 @@
  "zod": "4.4.3"
  },
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/content/docs/deployment/backup-restore.mdx b/content/docs/deployment/backup-restore.mdx
@@ -81,7 +81,7 @@ storage change. A backup you haven't restored is a hope, not a backup.
 
 ### Provision a clean host
 
-Fresh container or VM. Install Node 18+ and `@objectstack/cli`.
+Fresh container or VM. Install Node 22+ and `@objectstack/cli`.
 
 ### Restore the database
 

diff --git a/content/docs/deployment/self-hosting.mdx b/content/docs/deployment/self-hosting.mdx
@@ -49,7 +49,7 @@ The full catalog is in
 
 ## Option 1 — Bare Node.js (systemd)
 
-The simplest deployment: Node 18+ and the CLI on a Linux host.
+The simplest deployment: Node 22+ and the CLI on a Linux host.
 
 ```bash
 # On the host — no repo clone, just the CLI and your artifact

diff --git a/content/docs/deployment/troubleshooting.mdx b/content/docs/deployment/troubleshooting.mdx
@@ -317,7 +317,7 @@ Available subpaths: `data`, `api`, `ui`, `system`, `kernel`, `ai`, `automation`,
 
 ### What Node.js version is required?
 
-Node.js 18.0.0 or later. The `engines` field in `package.json` enforces this.
+Node.js 22.0.0 or later. The `engines` field in `package.json` enforces this.
 
 ### What TypeScript version is recommended?
 

diff --git a/content/docs/getting-started/build-with-claude-code.mdx b/content/docs/getting-started/build-with-claude-code.mdx
@@ -41,7 +41,7 @@ hand-edits generated glue, and no metadata mistake reaches the browser unchecked
 
 | You need | Why |
 |:---|:---|
-| **Node.js 18+** and npm (pnpm / yarn / bun also work) | Runs the scaffolder and the dev server (see [prerequisites](/docs/getting-started#prerequisites)). |
+| **Node.js 22+** and npm (pnpm / yarn / bun also work) | Runs the scaffolder and the dev server (see [prerequisites](/docs/getting-started#prerequisites)). |
 | **[Claude Code](https://claude.com/claude-code)** (or Cursor / Copilot) | Your agent reads `AGENTS.md` + the ObjectStack skills and authors the metadata. |
 
 ## 1. Scaffold the project

diff --git a/content/docs/getting-started/index.mdx b/content/docs/getting-started/index.mdx
@@ -156,7 +156,7 @@ Before you start, make sure you have the following installed:
 
 | Tool | Minimum Version | Check Command |
 |:---|:---|:---|
-| **Node.js** | 18.0.0+ | `node --version` |
+| **Node.js** | 22.0.0+ | `node --version` |
 
 That's everything the standard path needs — `npx create-objectstack my-app`
 scaffolds a project with its own TypeScript toolchain and npm scripts.

diff --git a/content/docs/getting-started/your-first-project.mdx b/content/docs/getting-started/your-first-project.mdx
@@ -22,7 +22,7 @@ without an agent. The two paths produce identical projects.
 
 | Tool | Minimum | Check |
 |:---|:---|:---|
-| **Node.js** | 18+ | `node --version` |
+| **Node.js** | 22+ | `node --version` |
 | A package manager | npm 9+ / pnpm 8+ / yarn / bun | `npm --version` |
 
 That's all. A standalone project does **not** need pnpm, TypeScript pre-installed,

diff --git a/examples/app-todo/README.md b/examples/app-todo/README.md
@@ -97,7 +97,7 @@ examples/app-todo/
 ## 💡 How to Run
 
 ### Prerequisites
-- Node.js 18+ and pnpm 8+
+- Node.js 22+ and pnpm 8+
 - Install from monorepo root: `corepack enable && pnpm install`
 
 ### Type Check

diff --git a/package.json b/package.json
@@ -60,7 +60,7 @@
  "typescript": "^6.0.3"
  },
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  },
  "packageManager": "pnpm@10.31.0+sha512.e3927388bfaa8078ceb79b748ffc1e8274e84d75163e67bc22e06c0d3aed43dd153151cbf11d7f8301ff4acb98c68bdc5cadf6989532801ffafe3b3e4a63c268",
  "pnpm": {

diff --git a/packages/adapters/hono/package.json b/packages/adapters/hono/package.json
@@ -54,6 +54,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/apps/account/package.json b/packages/apps/account/package.json
@@ -46,6 +46,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/apps/setup/package.json b/packages/apps/setup/package.json
@@ -46,6 +46,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/apps/studio/package.json b/packages/apps/studio/package.json
@@ -46,6 +46,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -123,6 +123,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/client-react/package.json b/packages/client-react/package.json
@@ -50,6 +50,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/client/package.json b/packages/client/package.json
@@ -54,6 +54,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/cloud-connection/package.json b/packages/cloud-connection/package.json
@@ -52,6 +52,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -57,6 +57,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/create-objectstack/package.json b/packages/create-objectstack/package.json
@@ -45,6 +45,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/lint/package.json b/packages/lint/package.json
@@ -53,6 +53,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -54,6 +54,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/metadata-core/package.json b/packages/metadata-core/package.json
@@ -66,6 +66,6 @@
  "access": "public"
  },
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/metadata-fs/package.json b/packages/metadata-fs/package.json
@@ -52,6 +52,6 @@
  "access": "public"
  },
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/metadata-protocol/package.json b/packages/metadata-protocol/package.json
@@ -56,6 +56,6 @@
  "access": "public"
  },
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/metadata/package.json b/packages/metadata/package.json
@@ -72,6 +72,6 @@
  "access": "public"
  },
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/objectql/package.json b/packages/objectql/package.json
@@ -58,6 +58,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/observability/package.json b/packages/observability/package.json
@@ -50,6 +50,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/platform-objects/package.json b/packages/platform-objects/package.json
@@ -100,6 +100,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/driver-memory/package.json b/packages/plugins/driver-memory/package.json
@@ -50,6 +50,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/driver-mongodb/package.json b/packages/plugins/driver-mongodb/package.json
@@ -53,6 +53,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/driver-sql/package.json b/packages/plugins/driver-sql/package.json
@@ -74,6 +74,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/driver-sqlite-wasm/package.json b/packages/plugins/driver-sqlite-wasm/package.json
@@ -57,6 +57,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/plugin-audit/package.json b/packages/plugins/plugin-audit/package.json
@@ -49,6 +49,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/plugin-auth/package.json b/packages/plugins/plugin-auth/package.json
@@ -59,6 +59,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/plugin-dev/package.json b/packages/plugins/plugin-dev/package.json
@@ -59,6 +59,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/plugin-hono-server/package.json b/packages/plugins/plugin-hono-server/package.json
@@ -45,6 +45,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/plugins/plugin-security/package.json b/packages/plugins/plugin-security/package.json
@@ -51,6 +51,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/rest/package.json b/packages/rest/package.json
@@ -58,6 +58,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }
diff --git a/packages/runtime/package.json b/packages/runtime/package.json
@@ -73,6 +73,6 @@
  "README.md"
  ],
  "engines": {
- "node": ">=18.0.0"
+ "node": ">=22.0.0"
  }
 }