From 6370f7f12f98c2063c8a7a6af6c87ec47eccf5b2 Mon Sep 17 00:00:00 2001 From: George Oastler Date: Fri, 18 Oct 2024 16:21:23 +0100 Subject: [PATCH 1/3] Explain environment variables from `package.json`, `.nvmrc` and `npm` --- docs/lib/content/using-npm/scripts.md | 65 +++++++++++++++++++-------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/docs/lib/content/using-npm/scripts.md b/docs/lib/content/using-npm/scripts.md index 75f8929bd99fe..545bf89b6396f 100644 --- a/docs/lib/content/using-npm/scripts.md +++ b/docs/lib/content/using-npm/scripts.md @@ -259,32 +259,61 @@ executing the scripts. So, if your package.json has this: then you could run `npm start` to execute the `bar` script, which is exported into the `node_modules/.bin` directory on `npm install`. -#### package.json vars +#### Environment variables from `package.json` -The package.json fields are tacked onto the `npm_package_` prefix. So, -for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your -package.json file, then your package scripts would have the -`npm_package_name` environment variable set to "foo", and the -`npm_package_version` set to "1.2.5". You can access these variables -in your code with `process.env.npm_package_name` and -`process.env.npm_package_version`, and so on for other fields. +Three fields of the `package.json` file are converted into environment variables prefixed with `npm_package_`. For example, if your `package.json` contains this: +```bash +{ + "name": "foo", + "version": "1.2.5", + "engines": { + "node": ">20" + } +} +``` +then these fields can be accessed in your code like so: +```js +console.log(process.env.npm_package_name) // prints "foo" +console.log(process.env.npm_package_version) // prints "1.2.5" +console.log(process.env.npm_package_engines_node) // prints ">20" +``` +Note that the keys in a nested field (such as the node engine) are flattened using `_` as a separator. -See [`package.json`](/configuring-npm/package-json) for more on package configs. +#### Environment variables from `npm` -#### current lifecycle event +The current state of npm is propagated to environment variables via: +- `npm_command`: the npm command being run. E.g. `run-script` when run using `npm run `. +- `npm_lifecycle_script`: the current script being executed. +- `npm_lifecycle_event`: the name of the script being executed. +- `npm_execpath`: the path to the npm cli file running this script. +- `npm_node_execpath`: the path to the node executable running this script. +- `npm_package_json`: the path to the `package.json` file containing this script. -Lastly, the `npm_lifecycle_event` environment variable is set to -whichever stage of the cycle is being executed. So, you could have a -single script used for different parts of the process which switches -based on what's currently happening. +For example if your `package.json` is +```bash +{ + "scripts": { + "start": "node index.js" + } +} +``` +then these fields can be accessed in your code like so: +```js +console.log(process.env.npm_lifecycle_event) // prints "start" +console.log(process.env.npm_lifecycle_script) // prints "node index.js" +``` -Objects are flattened following this format, so if you had -`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd -see this in the script: +#### Environment variables from `.npmrc` +Variables from the [`.npmrc` file](/cli/v10/using-npm/config#npmrc-files) (if used) are populated with the prefix `npm_config_`. For example, if your `.npmrc` file contains this: ```bash -process.env.npm_package_scripts_install === "foo.js" +script-shell="/bin/bash" +``` +then these variables can be accessed in your code like so: +```js +console.log(process.env.npm_config_script_shell) // prints "/bin/bash" ``` +Note that `-` is converted to `_` in the environment variable names. ### Examples From 15b0748d1f6e95d849acdeb26cf6122062eda869 Mon Sep 17 00:00:00 2001 From: George Oastler Date: Fri, 18 Oct 2024 16:37:41 +0100 Subject: [PATCH 2/3] Add `bin` and `config` env var docs --- docs/lib/content/using-npm/scripts.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/lib/content/using-npm/scripts.md b/docs/lib/content/using-npm/scripts.md index 545bf89b6396f..e5939d35c81d2 100644 --- a/docs/lib/content/using-npm/scripts.md +++ b/docs/lib/content/using-npm/scripts.md @@ -268,6 +268,12 @@ Three fields of the `package.json` file are converted into environment variables "version": "1.2.5", "engines": { "node": ">20" + }, + "config": { + "port": "3000" + }, + "bin": { + "cli": "path/to/cli" } } ``` @@ -276,8 +282,10 @@ then these fields can be accessed in your code like so: console.log(process.env.npm_package_name) // prints "foo" console.log(process.env.npm_package_version) // prints "1.2.5" console.log(process.env.npm_package_engines_node) // prints ">20" +console.log(process.env.npm_package_config_port) // prints "3000" +console.log(process.env.npm_package_bin_cli) // prints "path/to/cli" ``` -Note that the keys in a nested field (such as the node engine) are flattened using `_` as a separator. +Note that the keys in a nested field (such as `engines`, `bin` or `config`) are flattened using `_` as a separator. #### Environment variables from `npm` From bb08de1b48ef10824f81fef3394384b14a38b1a4 Mon Sep 17 00:00:00 2001 From: George Oastler Date: Fri, 18 Oct 2024 16:39:41 +0100 Subject: [PATCH 3/3] Fix wording for env var fields --- docs/lib/content/using-npm/scripts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/lib/content/using-npm/scripts.md b/docs/lib/content/using-npm/scripts.md index e5939d35c81d2..c256467938536 100644 --- a/docs/lib/content/using-npm/scripts.md +++ b/docs/lib/content/using-npm/scripts.md @@ -261,7 +261,7 @@ exported into the `node_modules/.bin` directory on `npm install`. #### Environment variables from `package.json` -Three fields of the `package.json` file are converted into environment variables prefixed with `npm_package_`. For example, if your `package.json` contains this: +Several fields of the `package.json` file are converted into environment variables prefixed with `npm_package_`. For example, if your `package.json` contains this: ```bash { "name": "foo",