Upgrade to Node 24 in local configuration and documentation

Author: lhotari

.nvmrc

@@ -0,0 +1 @@
+24

Dockerfile

@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-FROM node:22-bookworm as build
+FROM node:24-bookworm AS build
 
 WORKDIR /build-site
 

contribute/document-preview.md

@@ -17,57 +17,57 @@ Pulsar documentation is built using [Docusaurus](https://docusaurus.io/). To pre
 
 To verify docs are built correctly before submitting a contribution, you should set up your local environment to build and display the docs locally.
 
-* Node v20 LTS (there are compatibility issues with Node v23)
+* Node v24 LTS (Node v22 LTS also works; the pinned version in `.nvmrc` and CI is v24)
 * Corepack available and enabled (`corepack enable`)
 * Although you can use Linux, macOS, or Windows to build locally the Pulsar documentation, macOS is the preferred build environment as it offers the most complete support for documentation building.
 
-Installing prerequisites with [Homebrew](https://brew.sh/) on macOS or Linux:
+You can install Node.js with either **fnm** (recommended) or **Homebrew**. The repository ships a `.nvmrc` file, so fnm/nvm/asdf users will auto-select the right version.
+
+#### Option 1: fnm (recommended)
+
+[fnm](https://github.com/Schniz/fnm) is a fast, cross-platform Node version manager. It lets you run different Node versions per project without reinstalling, which is helpful when you contribute to multiple repositories.
+
+```shell
+# install fnm (macOS/Linux via Homebrew; see https://github.com/Schniz/fnm for other installers incl. Windows)
+brew install fnm
+# add shell integration; pick the line for your shell and append it to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
+eval "$(fnm env --use-on-cd --shell bash)"
+# install Node 24 LTS, enable corepack, and switch to it in the current shell (also picked up automatically from .nvmrc on 'cd' once shell integration is active)
+fnm install --corepack-enabled --use 24
+fnm default 24
+```
+
+#### Option 2: Homebrew
 
 ```shell
-# uninstall any existing node installation
-brew uninstall node
-# install node v20 LTS
-brew install node@20
-# link node v20
-brew link node@20
-# enable corepack
+# install Node (Homebrew's default node formula)
+brew install node
+# enable corepack (bundled with Node); only needs to run once per Node install
 corepack enable
 ```
 
+If you need to pin Node to a specific LTS line (e.g. to match CI), use fnm (Option 1) — it's easier than juggling Homebrew's versioned formulae.
+
 #### Troubleshooting Corepack installation - Homebrew installations on macOS or Linux
 
-Docusaurus supports Node v18 LTS and v20 LTS so ensure you have one of these versions installed.
-Sometimes Homebrew has Corepack installed, but it's not available.
+After a `brew upgrade` that bumps Node, Corepack-managed `yarn`/`pnpm` symlinks in Homebrew's `bin` can become dangling and break `yarn`. Similarly, a stale standalone `yarn` package installed via Homebrew can shadow the Corepack-managed one.
 
-Some commands to fix the `corepack` installation:
+To recover:
 
 ```shell
-# delete node symlinks if they exist
-brew unlink node
-# uninstall default node version
-brew uninstall node
-# uninstall yarn
-brew uninstall yarn
-# upgrade packages
+# upgrade packages so Node ships with a current Corepack
 brew upgrade
-# delete node@20 symlinks
-brew unlink node@20
-# install node v20 LTS if not already installed
-brew install node@20
-# recreate symlinks
-brew link node@20
-# delete broken symlinks in /opt/homebrew/bin
-find /opt/homebrew/bin -type l ! -exec test -e {} \; -delete
-# enable corepack, if the command fails, remove the conflicting files from `/opt/homebrew/bin` and try again
+# remove any stray yarn package (yarn should come from Corepack, not from Homebrew)
+brew uninstall yarn 2>/dev/null || true
+# delete broken symlinks in Homebrew's bin directory
+find "$(brew --prefix 2>/dev/null || echo "/opt/homebrew")/bin" -type l ! -exec test -e {} \; -delete
+# enable corepack; if the command fails, remove the conflicting files from the Homebrew bin directory and try again
 corepack enable
 ```
 
-Please also ensure that you have upgraded Homebrew packages to the latest versions. Run `brew upgrade` to upgrade all installed packages.
-
-Don't install `yarn` separately from a package manager since it's included with `corepack`, which is bundled with `node@20`. If you're using Homebrew, uninstall any existing `yarn` installation with `brew uninstall yarn` to avoid conflicts.
+Don't install `yarn` separately from a package manager since it's included with Corepack, which is bundled with Node. If you're using Homebrew, uninstall any existing `yarn` installation with `brew uninstall yarn` to avoid conflicts.
 
-If `corepack enable` fails due to file conflicts, verify that no legacy `corepack` or `yarn` package is already installed. If found, remove them. Removing `corepack` on updated Homebrew installations is not recommended since it uninstalls the `node@20` package.
-If `corepack enable` continues to fail due to conflicting files, manually remove the conflicting files from `/opt/homebrew/bin` and try again.
+If `corepack enable` continues to fail due to conflicting files, manually remove the conflicting files from the Homebrew bin directory (shown by `brew --prefix`) and try again.
 
 ### Preview changes
 

package.json

@@ -104,6 +104,6 @@
   },
   "packageManager": "yarn@3.5.0",
   "engines": {
-    "node": ">=18.0"
+    "node": ">=22.0"
   }
 }

preview.sh

@@ -18,12 +18,27 @@ BUILD_VERSIONS="${BUILD_VERSIONS}]"
 echo "$BUILD_VERSIONS" >.build-versions.json
 
 show_yarn_installation_help() {
-    echo "yarn is not available. yarn comes with corepack. corepack is part of the node runtime package in Homebrew."
-    echo "You will need to activate corepack by running:"
-    echo "corepack enable"
+    local brew_prefix
+    brew_prefix="$(brew --prefix 2>/dev/null || echo "/opt/homebrew")"
+    echo "*** yarn / Corepack is not working. ***"
+    echo
+    echo "If you see any of the following errors, the fix is almost always to run 'corepack enable':"
+    echo "  - 'command not found: yarn'"
+    echo "  - 'Internal Error: ... does not match the signature' / 'Cannot find matching keyid' (Corepack signature errors)"
+    echo "  - 'Cannot find module' errors when yarn starts"
+    echo "  - any other unexpected error from the Node.js package manager on a fresh machine"
+    echo
+    echo "Run this first:"
+    echo "  corepack enable"
+    echo
+    echo "Background: yarn is distributed via Corepack, which is bundled with the Node runtime."
+    echo "Corepack must be activated once per Node installation before yarn can be used."
+    echo
+    echo "Install Node.js 24 LTS either with fnm (https://github.com/Schniz/fnm) or with Homebrew."
     echo "Don't install yarn separately from a package manager. With Homebrew, uninstall any existing yarn installation with 'brew uninstall yarn'"
-    echo "You might have to run 'brew unlink node; brew link node; find /opt/homebrew/bin -type l ! -exec test -e {} \; -delete; corepack enable' to fix the installation."
-    echo "If 'corepack enable' fails due to file conflicts, remove the conflictings files manually from /opt/homebrew/bin and try again."
+    echo "If 'corepack enable' still fails, delete the broken symlinks in Homebrew's bin and run it again:"
+    echo "  find ${brew_prefix}/bin -type l ! -exec test -e {} \; -delete && corepack enable"
+    echo "If it still fails due to file conflicts, remove the conflicting files manually from ${brew_prefix}/bin and try again."
 }
 
 if ! command -v yarn &>/dev/null; then