This is an automated email from the ASF dual-hosted git repository. lhotari pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
commit d5da3ee5828eca70d2b7aec9b84b0e357400353d Author: Lari Hotari <[email protected]> AuthorDate: Wed Apr 22 18:48:34 2026 +0300 Upgrade to Node 24 in local configuration and documentation --- .nvmrc | 1 + Dockerfile | 2 +- contribute/document-preview.md | 66 +++++++++++++++++++++--------------------- package.json | 2 +- preview.sh | 25 ++++++++++++---- 5 files changed, 56 insertions(+), 40 deletions(-) diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 00000000000..a45fd52cc58 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +24 diff --git a/Dockerfile b/Dockerfile index 348be76ca91..129c32dda70 100644 --- a/Dockerfile +++ b/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 diff --git a/contribute/document-preview.md b/contribute/document-preview.md index 0dfe8914fbb..a154c132e61 100644 --- a/contribute/document-preview.md +++ b/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 diff --git a/package.json b/package.json index 1fb9b729929..7f5b3328fe8 100644 --- a/package.json +++ b/package.json @@ -104,6 +104,6 @@ }, "packageManager": "[email protected]", "engines": { - "node": ">=18.0" + "node": ">=22.0" } } diff --git a/preview.sh b/preview.sh index 91cea350d35..5decbbb3ce2 100755 --- a/preview.sh +++ b/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
