From 458c3afccde39523178ebd50ce3142d5218cef25 Mon Sep 17 00:00:00 2001 From: Boris Tyshkevich Date: Wed, 22 Jul 2026 19:10:20 +0200 Subject: [PATCH] Require Node.js 22 for development --- .npmrc | 1 + CHANGELOG.md | 6 ++++++ CLAUDE.md | 8 +++++--- README.md | 7 ++++++- docs/deployment.html | 4 +++- package-lock.json | 3 +++ package.json | 3 +++ 7 files changed, 27 insertions(+), 5 deletions(-) create mode 100644 .npmrc diff --git a/.npmrc b/.npmrc new file mode 100644 index 00000000..b6f27f13 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +engine-strict=true diff --git a/CHANGELOG.md b/CHANGELOG.md index fd9aefb4..9e7ee298 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/CLAUDE.md b/CLAUDE.md index e7f456e7..0bb2f489 100644 --- a/CLAUDE.md +++ b/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), diff --git a/README.md b/README.md index 9f797c02..c6dbd106 100644 --- a/README.md +++ b/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 diff --git a/docs/deployment.html b/docs/deployment.html index 7c9e9314..e9a83d29 100644 --- a/docs/deployment.html +++ b/docs/deployment.html @@ -46,7 +46,7 @@

Four deployment modes

Who it's forA whole team, shared URLOne developer, your laptopLocal/shared testingContributors Served fromClickHouse /sqllocalhost:8900/sqllocalhost:8900/sqllocalhost:8900/sql - PrerequisitesCluster admin + an IdPpython3 + curlDockerNode.js + npm + PrerequisitesCluster admin + an IdPpython3 + curlDockerNode.js 22+ + npm AuthSSO (OIDC) or BasicYour saved connectionsYour saved connectionsYour saved connections Connects toThat clusterAny cluster in your configAny cluster in your configAny cluster in your config Installdeploy/install.shone curl | shdocker compose up --buildnpm run local @@ -137,6 +137,8 @@

Run the existing local app in a container

Mode 4 · From source

Build and develop

+

Source builds require Node.js 22 or newer. With nvm, run + nvm use in the checkout to select the committed version.

git clone https://github.com/Altinity/altinity-sql-browser
 cd altinity-sql-browser
 npm ci
diff --git a/package-lock.json b/package-lock.json
index 3257a318..9f16cb58 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8,6 +8,9 @@
       "name": "altinity-sql-browser",
       "version": "0.6.1",
       "license": "Apache-2.0",
+      "engines": {
+        "node": ">=22"
+      },
       "dependencies": {
         "@codemirror/autocomplete": "^6.20.3",
         "@codemirror/commands": "^6.10.4",
diff --git a/package.json b/package.json
index d48fc0c0..21c2980d 100644
--- a/package.json
+++ b/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",