docs(common): update documentation for nvm usage

docs/build/linux-ubuntu.md

@@ -53,9 +53,13 @@ sudo mk-build-deps --install linux/debian/control
 
 #### Node.js
 
-Node.js v18 is required for Core builds, Web builds, and Developer command line tool builds and usage.
+Node.js is required for Core builds, Web builds, and Developer command line tool builds and usage.
 
-Follow the instructions on the [NodeSource Distributions](https://github.com/nodesource/distributions#table-of-contents) page.
+Our recommended way to install node.js is with
+[nvm](https://github.com/nvm-sh/nvm). This makes it easy to switch between
+versions of node.js.
+
+See [node.md](node.md) for more information.
 
 #### Emscripten
 

docs/build/macos.md

@@ -77,10 +77,24 @@ PATH="$HOMEBREW_PREFIX/opt/coreutils/libexec/gnubin:$PATH"
 
 ## KeymanWeb Dependencies
 
-* node.js 22+, emscripten 3.1.46 or later
+* node.js, emscripten 3.1.46 or later
+
+### node.js
+
+Our recommended way to install node.js is with
+[nvm](https://github.com/nvm-sh/nvm). This makes it easy to switch between
+versions of node.js.
+
+Alternatively, you can install node.js with `brew`.
+
+See [node.md](node.md) for more information.
+
+### emscripten
+
+To install emscripten:
 
 ```shell
-brew install node emscripten
+brew install emscripten
 ```
 
 Note: if you install emscripten with brew on macOS, only emscripten binaries are

docs/build/node.md

@@ -0,0 +1,71 @@
+# Node use in the Keyman project
+
+For a given release cycle, we select and pin to a specific version of node.js,
+and try to use that throughout. The version in use can be found in
+`package.json/engines.node`.
+
+If we encounter a blocking issue, we will upgrade to a known-good release, but
+this is exceptional.
+
+Generally, as a developer, if you use the same major version as is found in
+package.json, you probably won't have significant issues. However, if you are
+switching between stable branches and alpha branches, you may find the required
+node version changes.
+
+## Automatic node version selection
+
+The Keyman build system can be configured to manage the node.js version for you.
+This does have several caveats, so it is not enabled by default.
+
+When this is enabled, the build system will download the required node version
+and make it available on the PATH, and it will also stop the build if the node
+version mismatches. This happens in `build.sh configure` steps for any
+Typescript/Javascript project.
+
+To enable automatic node version selection, add the variable `KEYMAN_USE_NVM=1`
+to your environment.
+
+### Caveats
+
+nvm (for macOS/Linux) and nvm-windows use somewhat different paradigms, so the
+caveats vary per platform.
+
+### Caveats on macOS/Linux
+
+On macOS/Linux, nvm is provided as a shell function that modifies the current
+environment PATH to make a specific node version available -- and so this does
+not affect unrelated processes.
+
+1. You must use [nvm](https://github.com/nvm-sh/nvm) (macOS/Linux) to install
+   and manage Node versions.
+2. The Keyman build environment will create a symlink at `~/.keyman/node`
+   pointing to the version of node selected by nvm.
+3. You should add `$HOME/.keyman/node` to the front of your `PATH` variable,
+   e.g. in `~/.bash_profile`. This means that the node version _will_ be set for
+   the entire system, unlike with standard nvm usage. This allows build scripts
+   to run without calling `nvm` for each invocation.
+
+### Caveats on Windows
+
+On Windows, nvm-windows creates a symlink to the current node version, and
+this symlink is what is on the system PATH, so it affects all processes on the
+system.
+
+1. You must use [nvm-windows](https://github.com/coreybutler/nvm-windows) to
+   install and manage Node versions.
+2. By default on Windows, creating symlinks requires elevation. While
+   nvm-windows does this for you, it can be irritating to have a build script
+   pause for elevation. In Local Group Policy Editor, `Computer Configuration`,
+   `Windows Settings`, `Security Settings`, `Local Policies`,
+   `User Rights Assignment`, you can add your username to the
+   `Create symbolic links` policy (and reboot), to avoid elevation.
+
+## Build Agents
+
+The Keyman build agents use nvm as described above, including the caveats.
+
+## Implementation
+
+See `_select_node_version_with_nvm()` in
+`/resources/build/shellHelperFunctions.sh`, and
+`/resources/build/_builder_nvm.sh`.

docs/build/windows.md

@@ -206,7 +206,15 @@ installed emsdk (most likely %LocalAppData%\emsdk\upstream\emscripten)
 **Environment variables**:
 * `EMSCRIPTEN_BASE`: `<your-emsdk-path>\upstream\emscripten`
 
-After installing emscripten, you'll need to install node.js and openjdk:
+After installing emscripten, you'll need to install node.js and openjdk.
+
+#### node.js
+
+Our recommended way to install node.js is to use
+[nvm-windows](https://github.com/coreybutler/nvm-windows). This makes it
+easy to switch between versions of node.js.
+
+Alternatively, use Powershell + Chocolatey to install node.js:
 
 ```ps1
 # Elevated PowerShell
@@ -214,9 +222,23 @@ After installing emscripten, you'll need to install node.js and openjdk:
 # for *much* faster download, hide progress bar (PowerShell/PowerShell#2138)
 $ProgressPreference = 'SilentlyContinue'
 choco install nodejs
+```
+
+See [node.md](node.md) for more information.
+
+#### openjdk
+
+Use Powershell + Chocolatey to install OpenJDK:
+
+```ps1
+# Elevated PowerShell
+
+# for *much* faster download, hide progress bar (PowerShell/PowerShell#2138)
+$ProgressPreference = 'SilentlyContinue'
 choco install openjdk
 ```
 
+
 ### Windows Platform Dependencies
 
 **Projects**: