From 737ff48b2f7c319aae36eb5828602e60fb9b5354 Mon Sep 17 00:00:00 2001
From: zjncs <18910855655@163.com>
Date: Wed, 21 Oct 2026 13:57:18 +0800
Subject: [PATCH] fix(dev): pin the web toolchain to Node 20/22
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

jsdom-based web unit tests silently break on Node 25 (window.localStorage
degrades to a plain object, see #991) while CI stays green on its pinned
Node 20 — a confusing failure mode for new contributors on bleeding-edge
Node. Pins the local default via .nvmrc, declares engines in
web/package.json, and spells out the supported versions in CONTRIBUTING.

Signed-off-by: zjncs <18910855655@163.com>
---
 .nvmrc           | 1 +
 CONTRIBUTING.md  | 2 +-
 web/package.json | 3 +++
 3 files changed, 5 insertions(+), 1 deletion(-)
 create mode 100644 .nvmrc

diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 000000000..209e3ef4b
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+20
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c7c57d04..dad2d10a6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Prerequisites:
 
 - Docker and Docker Compose
 - Java 21
-- Node.js and `pnpm`
+- Node.js 20 or 22 (see `.nvmrc`; Node 25+ currently breaks jsdom-based web tests — #991) and `pnpm`
 
 Start the local stack:
 
diff --git a/web/package.json b/web/package.json
index ac1340ec4..a1d9924c1 100644
--- a/web/package.json
+++ b/web/package.json
@@ -92,5 +92,8 @@
     "typescript": "^5.7.0",
     "vite": "^6.4.3",
     "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20 <25"
   }
 }