From 8b0e9a9b7ae0d23c825f49c06e93dc8d52947ba1 Mon Sep 17 00:00:00 2001
From: Mike McCready <66998419+MikeMcC399@users.noreply.github.com>
Date: Sun, 26 Jul 2026 08:44:09 +0200
Subject: [PATCH] docs: add instructions to upgrade npm

---
 docs/BestPractices.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/BestPractices.md b/docs/BestPractices.md
index de5461846..58217745f 100644
--- a/docs/BestPractices.md
+++ b/docs/BestPractices.md
@@ -6,6 +6,7 @@
 ## Table of Contents
 
 - [Environment Variables](#environment-variables)
+- [Upgrading npm](#upgrading-npm)
 - [Global npm dependencies](#global-npm-dependencies)
 - [Handling Kernel Signals](#handling-kernel-signals)
 - [Non-root User](#non-root-user)
@@ -27,6 +28,25 @@ Run with `NODE_ENV` set to `production`. This is the way you would pass in secre
 -e "NODE_ENV=production"
 ```
 
+## Upgrading npm
+
+Each `node` Docker image includes npm, bundled with Node.js.
+You can check the version from the CLI, for example:
+
+```shell
+docker run --rm --entrypoint npm node:lts --version
+```
+
+The bundled npm version is also listed in the detail information on the
+[Node.js Releases](https://nodejs.org/en/about/previous-releases) page.
+If you need to upgrade (or downgrade) the version of npm,
+add the following to your `Dockerfile`, replacing `<version>` with the desired value.
+View the [npm registry listing](https://www.npmjs.com/package/npm?activeTab=versions) for available versions and tags.
+
+```Dockerfile
+RUN npm install --global npm@<version>
+```
+
 ## Global npm dependencies
 
 If you need to install global npm dependencies, it is recommended to place those dependencies in the [non-root user](#non-root-user) directory. To achieve this, add the following line to your `Dockerfile`
@@ -37,6 +57,8 @@ ENV NPM_CONFIG_PREFIX=/home/node/.npm-global
 ENV PATH=$PATH:/home/node/.npm-global/bin # optionally if you want to run npm global bin without specifying path
 ```
 
+This recommendation does not apply to npm itself, which is installed in `/usr/local/bin/npm`.
+
 ## Handling Kernel Signals
 
 Node.js was not designed to run as PID 1 which leads to unexpected behaviour when running inside of Docker. For example, a Node.js process running as PID 1 will not respond to `SIGINT` (`CTRL-C`) and similar signals. As of Docker 1.13, you can use the `--init` flag to wrap your Node.js process with a [lightweight init system](https://github.com/krallin/tini) that properly handles running as PID 1.