From 4a745296b209589d0208b7e654da21c01e8c045a Mon Sep 17 00:00:00 2001 From: Oliver Byford Date: Thu, 21 May 2026 16:49:18 +0100 Subject: [PATCH] docs: Document `npm_old_version` and `npm_new_version` environment variables (#9385) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit npm sets two additional environment variables `npm_old_version` and `npm_new_version` when running the `preversion`, `version`, `postversion` scripts, but these aren’t documented anywhere. Document the variables in the ‘Scripts’ docs, and cross-reference them from the documentation for the version command (and the libnpmversion readme). I've tried to match the existing formatting conventions for each document. Please let me know if anything needs to change. (cherry picked from commit d124c0858da0b138cda2addcb0987b063ca86a47) --- docs/lib/content/commands/npm-version.md | 2 ++ docs/lib/content/using-npm/scripts.md | 7 +++++++ workspaces/libnpmversion/README.md | 3 +++ 3 files changed, 12 insertions(+) diff --git a/docs/lib/content/commands/npm-version.md b/docs/lib/content/commands/npm-version.md index 4ea0837aa8446..a9bb4dab66717 100644 --- a/docs/lib/content/commands/npm-version.md +++ b/docs/lib/content/commands/npm-version.md @@ -70,6 +70,8 @@ The exact order of execution is as follows: 6. Run the `postversion` script. Use it to clean up the file system or automatically push the commit and/or tag. +For the `preversion`, `version` and `postversion` scripts, npm also sets the [environment variables](/using-npm/scripts#environment) `npm_old_version` and `npm_new_version`. + Take the following example: ```json diff --git a/docs/lib/content/using-npm/scripts.md b/docs/lib/content/using-npm/scripts.md index 380c4aa49e36f..b01c0bc7ffd77 100644 --- a/docs/lib/content/using-npm/scripts.md +++ b/docs/lib/content/using-npm/scripts.md @@ -290,6 +290,13 @@ For example, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json See [`package.json`](/configuring-npm/package-json) for more on package configs. +#### versioning variables + +For versioning scripts (`preversion`, `version`, `postversion`), npm sets these environment variables: + +* `npm_old_version` - The version before being bumped +* `npm_new_version` – The version after being bumped + #### current lifecycle event Lastly, the `npm_lifecycle_event` environment variable is set to whichever stage of the cycle is being executed. diff --git a/workspaces/libnpmversion/README.md b/workspaces/libnpmversion/README.md index b81a231d05ce0..d60a144bcc1bf 100644 --- a/workspaces/libnpmversion/README.md +++ b/workspaces/libnpmversion/README.md @@ -86,6 +86,9 @@ The exact order of execution is as follows: 6. Run the `postversion` script. Use it to clean up the file system or automatically push the commit and/or tag. +For the `preversion`, `version` and `postversion` scripts, npm also sets the +environment variables `npm_old_version` and `npm_new_version`. + Take the following example: ```json