Require Node.js >= 25 (engines, installers, Dockerfile, snap, CI, docs) (#7749)

JohnMcLear · claude · web-flow · commit 7d537f3debfa · 2026-05-15T10:04:24.000+01:00
* docs: bump documented Node.js minimum to 25 Etherpad is moving its supported Node.js floor to >= 25 (CI matrix is already pinned to 25 across all workflows on the node25-corepack-pnpm11 work). Sync the user-facing documentation so the install instructions, requirements section, and plugin metadata example all reflect the new minimum instead of Node 22 / 12.17. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: require Node.js >= 25 (engines, installers, Dockerfile, snap, CI) #7747 added Node 25 *support* but left the floor at Node 22. This commit completes the cutover so the runtime requirement matches the documentation bumped in the previous commit. - package.json: engines.node ">=22.13.0" → ">=25.0.0" - bin/functions.sh, bin/installer.sh, bin/installer.ps1: REQUIRED_NODE bumped to 25 (controls the error message users see when they invoke the installer or pnpm scripts on an older Node) - Dockerfile: base image node:22-alpine → node:25-alpine (×2). Corepack comment updated: Node 25 no longer ships corepack at all, so we install it from npm rather than refreshing a stale signing-key list - snap/snapcraft.yaml: pinned NODE_VERSION 22.22.2 → 25.9.0 and the surrounding design notes rewritten to reflect Node 25 instead of 22 - .github/workflows/*.yml: matrix dropped from [22, 24, 25] to just [25] (anything older now fails engines anyway). Stale comments in build-and-deploy-docs.yml referencing vite 8's 22.12 floor cleaned up - bin/plugins/lib/npmpublish.yml: setup-node 22 → 25 so the plugin template propagated to every ether/* plugin matches the new minimum Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(docker): install pnpm directly on Node 25 (no corepack) node:25-alpine doesn't ship corepack but does pre-install yarn at /usr/local/bin/yarn, so `npm install -g corepack@latest` fails with EEXIST trying to register its yarn shim. Per #7747, end-users install pnpm via plain `npm install -g pnpm` on Node 25 — use the same flow in the Dockerfile (and remove the unused yarn binary so it doesn't sit on PATH inside the image). Drops COREPACK_HOME and the related issue-7687 cache-sharing tweak since there's no corepack shim to share. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/.github/workflows/backend-tests.yml b/.github/workflows/backend-tests.yml
@@ -27,8 +27,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # PRs: test on latest Node only. Push to develop: full matrix.
-        node: ${{ github.event_name == 'pull_request' && fromJSON('[25]') || fromJSON('[22, 24, 25]') }}
+        # Etherpad requires Node >= 25 (see package.json engines.node).
+        node: ${{ fromJSON('[25]') }}
     steps:
       -
         name: Checkout repository
@@ -101,7 +101,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: ${{ github.event_name == 'pull_request' && fromJSON('[25]') || fromJSON('[22, 24, 25]') }}
+        node: ${{ fromJSON('[25]') }}
     steps:
       -
         name: Checkout repository
diff --git a/.github/workflows/build-and-deploy-docs.yml b/.github/workflows/build-and-deploy-docs.yml
@@ -56,8 +56,7 @@ jobs:
         with:
           run_install: false
       # Pin Node so the build does not silently fall back to whatever the
-      # runner image ships with. vite 8 requires Node ^20.19.0 || >=22.12.0;
-      # the repo declares engines.node >=22.12.0 to match.
+      # runner image ships with. The repo declares engines.node >=25.0.0.
       - name: Use Node.js
         uses: actions/setup-node@v6
         with:
diff --git a/.github/workflows/frontend-admin-tests.yml b/.github/workflows/frontend-admin-tests.yml
@@ -21,8 +21,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # PRs: single Node version. Push: full matrix.
-        node: ${{ github.event_name == 'pull_request' && fromJSON('[25]') || fromJSON('[22, 24, 25]') }}
+        # Etherpad requires Node >= 25 (see package.json engines.node).
+        node: ${{ fromJSON('[25]') }}
 
     steps:
       -
diff --git a/.github/workflows/upgrade-from-latest-release.yml b/.github/workflows/upgrade-from-latest-release.yml
@@ -27,8 +27,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # PRs: single Node version. Push: full matrix.
-        node: ${{ github.event_name == 'pull_request' && fromJSON('[25]') || fromJSON('[22, 24, 25]') }}
+        # Etherpad requires Node >= 25 (see package.json engines.node).
+        node: ${{ fromJSON('[25]') }}
     steps:
       -
         name: Check out latest release
diff --git a/Dockerfile b/Dockerfile
@@ -9,22 +9,22 @@ ARG BUILD_ENV=git
 
 ARG PnpmVersion=11.0.6
 
-FROM node:22-alpine AS adminbuild
-# Use corepack to provision pnpm and drop the bundled npm — its older
-# transitives (picomatch, brace-expansion) carry CVEs we don't otherwise
-# need. Refresh corepack first: the version bundled with Node 22 ships a
-# stale signing-key list and rejects newer pnpm releases
-# (nodejs/corepack#612). Mirrors the workaround in snap/snapcraft.yaml.
-RUN npm install -g corepack@latest && \
-    corepack enable && corepack prepare pnpm@${PnpmVersion} --activate && \
+FROM node:25-alpine AS adminbuild
+# Node 25 no longer ships corepack at all, so install pnpm directly via
+# npm. The node:25-alpine image also bundles yarn; remove it first to
+# avoid leaving an unused binary on PATH. Drop bundled npm afterwards
+# — its older transitives (picomatch, brace-expansion) carry CVEs we
+# don't otherwise need.
+RUN rm -f /usr/local/bin/yarn /usr/local/bin/yarnpkg && \
+    npm install -g pnpm@${PnpmVersion} && \
     rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
 WORKDIR /opt/etherpad-lite
 COPY . .
 RUN pnpm install
 RUN pnpm run build:ui
 
 
-FROM node:22-alpine AS build
+FROM node:25-alpine AS build
 LABEL maintainer="Etherpad team, https://github.com/ether/etherpad"
 
 # Set these arguments when building the image from behind a proxy
@@ -99,21 +99,16 @@ RUN groupadd --system ${EP_GID:+--gid "${EP_GID}" --non-unique} etherpad && \
 ARG EP_DIR=/opt/etherpad-lite
 RUN mkdir -p "${EP_DIR}" && chown etherpad:etherpad "${EP_DIR}"
 
-# Share corepack's cache between root (which activates pnpm here) and
-# the `etherpad` user (which invokes pnpm later via the corepack shim).
-# $COREPACK_HOME defaults to ~/.cache/node/corepack and is per-user;
-# without this pin the etherpad user finds an empty cache, re-resolves
-# pnpm, and corepack can fall back to "latest" from the registry. See
-# https://github.com/ether/etherpad/issues/7687.
-ENV COREPACK_HOME=/opt/corepack
-
+# Node 25 dropped corepack; install pnpm directly via npm, then drop
+# both npm and the pre-bundled yarn binary to keep the runtime image
+# free of unused tooling and known-CVE transitives.
+#
 # the mkdir is needed for configuration of openjdk-11-jre-headless, see
 # https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=863199
 RUN  \
-    mkdir -p /usr/share/man/man1 "${COREPACK_HOME}" && \
-    npm install -g corepack@latest && \
-    corepack enable && corepack prepare pnpm@${PnpmVersion} --activate && \
-    chown -R etherpad:etherpad "${COREPACK_HOME}" && \
+    mkdir -p /usr/share/man/man1 && \
+    rm -f /usr/local/bin/yarn /usr/local/bin/yarnpkg && \
+    npm install -g pnpm@${PnpmVersion} && \
     rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx && \
     apk update && apk upgrade && \
     apk add --no-cache \
diff --git a/README.md b/README.md
@@ -64,7 +64,7 @@ For more than a decade, Etherpad has quietly underpinned the documents that matt
 
 ### Quick install (one-liner)
 
-The fastest way to get Etherpad running. Requires `git` and Node.js >= 22.
+The fastest way to get Etherpad running. Requires `git` and Node.js >= 25.
 
 **macOS / Linux / WSL:**
 
@@ -158,7 +158,7 @@ volumes:
 
 ### Requirements
 
-[Node.js](https://nodejs.org/) >= 22.12.
+[Node.js](https://nodejs.org/) >= 25.
 
 ### Windows, macOS, Linux
 
diff --git a/bin/functions.sh b/bin/functions.sh
@@ -1,5 +1,5 @@
 # minimum required node version
-REQUIRED_NODE_MAJOR=22
+REQUIRED_NODE_MAJOR=25
 REQUIRED_NODE_MINOR=0
 
 # minimum required npm version
diff --git a/bin/installer.ps1 b/bin/installer.ps1
@@ -38,7 +38,7 @@ function Test-Cmd([string]$name) {
 $EtherpadDir    = if ($env:ETHERPAD_DIR)    { $env:ETHERPAD_DIR }    else { 'etherpad-lite' }
 $EtherpadBranch = if ($env:ETHERPAD_BRANCH) { $env:ETHERPAD_BRANCH } else { 'master' }
 $EtherpadRepo   = if ($env:ETHERPAD_REPO)   { $env:ETHERPAD_REPO }   else { 'https://github.com/ether/etherpad.git' }
-$RequiredNodeMajor = 22
+$RequiredNodeMajor = 25
 
 Write-Step 'Etherpad installer'
 
diff --git a/bin/installer.sh b/bin/installer.sh
@@ -34,7 +34,7 @@ is_cmd() { command -v "$1" >/dev/null 2>&1; }
 ETHERPAD_DIR="${ETHERPAD_DIR:-etherpad-lite}"
 ETHERPAD_BRANCH="${ETHERPAD_BRANCH:-master}"
 ETHERPAD_REPO="${ETHERPAD_REPO:-https://github.com/ether/etherpad.git}"
-REQUIRED_NODE_MAJOR=22
+REQUIRED_NODE_MAJOR=25
 
 step "Etherpad installer"
 
diff --git a/bin/plugins/lib/npmpublish.yml b/bin/plugins/lib/npmpublish.yml
@@ -21,9 +21,9 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           # OIDC trusted publishing needs npm >= 11.5.1, which requires
-          # Node >= 22.9.0. setup-node's `22` resolves to the latest
-          # 22.x, which satisfies that.
-          node-version: 22
+          # Node >= 22.9.0. Use Node 25 to match the rest of CI and the
+          # Etherpad core minimum.
+          node-version: 25
           registry-url: https://registry.npmjs.org/
       - name: Upgrade npm to >=11.5.1 (required for trusted publishing)
         run: npm install -g npm@latest
diff --git a/doc/npm-trusted-publishing.md b/doc/npm-trusted-publishing.md
@@ -85,10 +85,9 @@ If a package previously had an `NPM_TOKEN` secret in CI:
 
 ## Requirements
 
-- **Node.js**: >= 22.12 on the runner. npm 11 requires `>=22.9.0` and
-  `oxc-minify` (a vitepress peer for the docs build) requires `>=22.12.0`,
-  both of which `setup-node@v6 with version: 22` satisfies (resolves to the
-  latest 22.x). The project's `engines.node` requires `>=22.12.0`.
+- **Node.js**: >= 25 on the runner. `setup-node@v6 with version: 25`
+  resolves to the latest 25.x. The project's `engines.node` requires
+  `>=25.0.0`.
 - **npm CLI**: >= 11.5.1. The publish workflow runs `npm install -g npm@latest`
   before publishing so the bundled npm version doesn't matter.
 - **Runner**: must be a GitHub-hosted (cloud) runner. Self-hosted runners are
diff --git a/doc/plugins.adoc b/doc/plugins.adoc
@@ -231,7 +231,7 @@ publish your plugin.
   "author": "USERNAME (REAL NAME) <MAIL@EXAMPLE.COM>",
   "contributors": [],
   "dependencies": {"MODULE": "0.3.20"},
-  "engines": {"node": ">=12.17.0"}
+  "engines": {"node": ">=25.0.0"}
 }
 ----
 
diff --git a/doc/plugins.md b/doc/plugins.md
@@ -226,7 +226,7 @@ publish your plugin.
   "author": "USERNAME (REAL NAME) <MAIL@EXAMPLE.COM>",
   "contributors": [],
   "dependencies": {"MODULE": "0.3.20"},
-  "engines": {"node": ">=12.17.0"}
+  "engines": {"node": ">=25.0.0"}
 }
 ```
 
diff --git a/package.json b/package.json
@@ -42,7 +42,7 @@
     "ui": "link:ui"
   },
   "engines": {
-    "node": ">=22.13.0",
+    "node": ">=25.0.0",
     "pnpm": ">=11.1.2"
   },
   "packageManager": "pnpm@11.1.2",
diff --git a/snap/snapcraft.yaml b/snap/snapcraft.yaml
@@ -1,22 +1,22 @@
 # snap/snapcraft.yaml — Snap recipe for Etherpad
 #
 # Design notes:
-# - base: core24 chosen because Etherpad requires Node.js >= 20 and
+# - base: core24 chosen because Etherpad requires Node.js >= 25 and
 #   core24 (Ubuntu 24.04 LTS) ships glibc/OpenSSL versions matching modern
-#   Node 20/22 binaries. core22 also works but ships older TLS/CA bundles.
+#   Node 25 binaries. core22 also works but ships older TLS/CA bundles.
 # - confinement: strict. Etherpad is a pure Node.js HTTP service. The only
 #   native Node module (`rusty-store-kv`) ships as a prebuilt napi-rs
 #   binary, so no node-gyp compile is performed at install time and
 #   strict confinement works cleanly.
 # - We use `dump` + a manual override-build (rather than the npm plugin)
-#   because this repo is a pnpm workspace and we pin Node.js 22 manually.
+#   because this repo is a pnpm workspace and we pin Node.js 25 manually.
 name: etherpad
 title: Etherpad
 summary: Real-time collaborative document editor
 description: |
   Etherpad is a highly customizable open-source online editor providing
   collaborative editing in real-time. This snap bundles Etherpad with a
-  pinned Node.js 22 runtime. On first launch a default `settings.json`
+  pinned Node.js 25 runtime. On first launch a default `settings.json`
   is copied into `$SNAP_COMMON/etc` where it can be edited. Pad data is
   stored in `$SNAP_COMMON/var` and survives snap refreshes.
 
@@ -91,9 +91,9 @@ parts:
     override-build: |
       set -eu
 
-      # -- 1. Install Node.js 22 from the official tarball. Must be >=22.13
-      # because pnpm 11 hard-rejects older 22.x releases.
-      NODE_VERSION=22.22.2
+      # -- 1. Install Node.js 25 from the official tarball. Node 25 is the
+      # minimum supported runtime (see package.json engines.node).
+      NODE_VERSION=25.9.0
       ARCH="$(dpkg --print-architecture)"
       case "${ARCH}" in
         amd64) NODE_ARCH=x64 ;;
@@ -109,9 +109,8 @@ parts:
 
       export PATH="${CRAFT_PART_INSTALL}/opt/node/bin:${PATH}"
 
-      # -- 2. Install pnpm via corepack. The corepack version bundled with
-      # Node 22.12 ships a stale signing-key list and rejects newer pnpm
-      # releases (nodejs/corepack#612), so refresh corepack itself first.
+      # -- 2. Install pnpm via corepack. Node 25 distributions no longer
+      # ship corepack, so install it from npm before activating pnpm.
       "${CRAFT_PART_INSTALL}/opt/node/bin/npm" install \
         --prefix "${CRAFT_PART_INSTALL}/opt/node" -g corepack@latest
       corepack enable --install-directory "${CRAFT_PART_INSTALL}/opt/node/bin"
