Require Node.js 22 for local development

.npmrc

@@ -0,0 +1 @@
+engine-strict=true

CHANGELOG.md

@@ -9,6 +9,12 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
 
 ## [Unreleased]
 
+### Fixed
+- Declared Node.js 22 as the minimum source-development runtime, kept the
+  committed `.nvmrc` as the version-manager default, and enabled strict npm
+  engine checks so unsupported local installs fail before the test runner
+  reaches incompatible dependencies (#383).
+
 ### Changed
 - Consolidated the non-Iceberg examples into three responsive flagship
   dashboards: On-time flights, Shop analytics, and ClickHouse Operations.

CLAUDE.md

@@ -33,9 +33,11 @@ all bundled — see hard rule 4). Quality is held by tests.
    (see README "Configuring OAuth").
 4. **The build is esbuild only; runtime deps are rare and deliberate.** Source
    files are the tested files; esbuild bundles `src/main.ts` → `dist/sql.html`.
-   `package-lock.json` is committed; use `npm ci` for a reproducible dependency
-   graph in local, CI, and release builds, and update the lock only with an
-   intentional dependency change.
+   Source development requires Node.js 22 or newer; `.nvmrc` selects Node 22,
+   `package.json` declares the minimum, and `.npmrc` makes unsupported installs
+   fail clearly. `package-lock.json` is committed; use `npm ci` for a
+   reproducible dependency graph in local, CI, and release builds, and update
+   the lock only with an intentional dependency change.
    There are **six** bundled runtime dependencies — **CodeMirror 6** (the SQL
    editor, saved-query Spec JSON editor, and read-only source viewer, behind
    injected seams — #21/#212/#213),

README.md

@@ -511,7 +511,12 @@ FROM ontime
 
 ## Quick start (development)
 
+Source development requires **Node.js 22 or newer**. The committed `.nvmrc`
+selects Node 22 for version managers such as `nvm`; `npm ci` exits with an
+unsupported-engine error on older Node releases.
+
 ```bash
+nvm use                # optional; reads Node 22 from .nvmrc
 npm ci                 # exact dependency tree from the committed lockfile
 npm test               # vitest + 100% coverage gate
 npm run build          # → dist/sql.html (single file)
@@ -634,7 +639,7 @@ different interface. The probe **prints a reachability table** and skips any hos
 with no HTTP interface on any port (e.g. a native-only endpoint) so it isn't a dead
 pick. Set `SQL_BROWSER_PROBE=0` to skip probing and keep all hosts (`8443`/`8123`).
 
-**From a checkout** (also builds the SPA, needs Node):
+**From a checkout** (also builds the SPA, requires Node.js 22 or newer):
 
 ```bash
 npm run local          # build + serve → open http://localhost:8900/sql

docs/deployment.html

@@ -46,7 +46,7 @@ <h1>Four deployment modes</h1>
         <tbody>
           <tr><td class="feat">Who it's for</td><td>A whole team, shared URL</td><td>One developer, your laptop</td><td>Local/shared testing</td><td>Contributors</td></tr>
           <tr><td class="feat">Served from</td><td>ClickHouse <code class="k">/sql</code></td><td><code class="k">localhost:8900/sql</code></td><td><code class="k">localhost:8900/sql</code></td><td><code class="k">localhost:8900/sql</code></td></tr>
-          <tr><td class="feat">Prerequisites</td><td>Cluster admin + an IdP</td><td><code class="k">python3</code> + curl</td><td>Docker</td><td>Node.js + npm</td></tr>
+          <tr><td class="feat">Prerequisites</td><td>Cluster admin + an IdP</td><td><code class="k">python3</code> + curl</td><td>Docker</td><td>Node.js 22+ + npm</td></tr>
           <tr><td class="feat">Auth</td><td class="yes">SSO (OIDC) or Basic</td><td>Your saved connections</td><td>Your saved connections</td><td>Your saved connections</td></tr>
           <tr><td class="feat">Connects to</td><td>That cluster</td><td>Any cluster in your config</td><td>Any cluster in your config</td><td>Any cluster in your config</td></tr>
           <tr><td class="feat">Install</td><td><code class="k">deploy/install.sh</code></td><td>one <code class="k">curl | sh</code></td><td><code class="k">docker compose up --build</code></td><td><code class="k">npm run local</code></td></tr>
@@ -137,6 +137,8 @@ <h2>Run the existing local app in a container</h2>
   <div class="wrap narrow">
     <div class="eyebrow">Mode 4 · From source</div>
     <h2>Build and develop</h2>
+    <p>Source builds require Node.js 22 or newer. With <code class="k">nvm</code>, run
+      <code class="k">nvm use</code> in the checkout to select the committed version.</p>
     <pre class="code">git clone https://github.com/Altinity/altinity-sql-browser
 cd altinity-sql-browser
 npm ci

package.json

@@ -5,6 +5,9 @@
   "description": "A self-contained, OAuth-gated SQL browser for any ClickHouse cluster. Vanilla ES modules, served from ClickHouse itself as one HTML file with zero third-party requests.",
   "type": "module",
   "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "prebuild": "npm run check:schemas",
     "build": "node build/build.mjs",