chore: upgrade to NPM v12

.github/actions/install-npm/action.yml

@@ -0,0 +1,14 @@
+name: Install NPM
+description: >
+  Installs the NPM version required by the `engines.npm` directive in
+  package.json, which is required for the project to build correctly.
+
+runs:
+  using: composite
+  steps:
+    - name: Install NPM
+      shell: bash
+      run: |
+        npmVersion="$(node -p 'require(`${process.env.GITHUB_WORKSPACE}/package.json`).engines.npm')"
+        echo "Installing npm@${npmVersion}"
+        npm install -g "npm@${npmVersion}"

.github/workflows/deploy.yaml

@@ -29,6 +29,9 @@ jobs:
           node-version: "22.x"
           cache: "npm"
 
+      - name: Install NPM version specified in package.json
+        uses: ./.github/actions/install-npm
+
       - name: Install dependencies
         run: npm ci --no-audit
 

.github/workflows/test-and-release.yaml

@@ -18,6 +18,9 @@ jobs:
           node-version: "22.x"
           cache: "npm"
 
+      - name: Install NPM version specified in package.json
+        uses: ./.github/actions/install-npm
+
       - name: Install dependencies
         run: npm ci --no-audit
 
@@ -75,6 +78,9 @@ jobs:
           node-version: "22.x"
           cache: "npm"
 
+      - name: Install NPM version specified in package.json
+        uses: ./.github/actions/install-npm
+
       - name: Install dependencies
         run: npm ci --no-audit --force
 
@@ -113,6 +119,9 @@ jobs:
           node-version: "22.x"
           cache: "npm"
 
+      - name: Install NPM version specified in package.json
+        uses: ./.github/actions/install-npm
+
       - name: Semantic release
         run: npx semantic-release
         env:

README.md

@@ -119,3 +119,13 @@ Run the interactive code generator:
 ```bash
 npx playwright codegen
 ```
+
+## Node & NPM
+
+This project requires Node.js `>=20.0.0` and npm `>=12.0.2 <13` (enforced via
+`check-node-version` on `npm install` and `npm ci`).
+
+The check is skipped during `npm publish` and `npm pack`, because
+`semantic-release` bundles its own npm (`@semantic-release/npm` depends on
+`npm@^11.6.2`) and runs the publish with that version rather than the one
+installed in CI.

package.json

@@ -22,7 +22,7 @@
     "start": "vite",
     "start:e2e": "vite -c e2e-tests/vite.config.e2e.ts",
     "build": "node --max_old_space_size=8192 ./node_modules/vite/bin/vite.js build --emptyOutDir",
-    "prepare": "husky",
+    "prepare": "husky && case \"$npm_command\" in install|ci) check-node-version --package ;; esac",
     "test": "npx globstar -- npx tsx --test --test-reporter spec \"!(node_modules|e2e-tests)/**/*.spec.ts\"",
     "test:e2e": "npx playwright test --project chromium"
   },
@@ -39,6 +39,7 @@
     "@types/jsonwebtoken": "9.0.10",
     "@types/node": "24.9.1",
     "@types/semver": "7.7.1",
+    "check-node-version": "4.2.1",
     "commitlint": "19.8.1",
     "glob": "11.1.0",
     "globstar": "1.0.0",
@@ -67,7 +68,7 @@
   },
   "engines": {
     "node": ">=20.0.0",
-    "npm": ">=9.0.0"
+    "npm": ">=12.0.2 <13"
   },
   "lint-staged": {
     "*.{ts,tsx}": [