doc: add new environment variables doc page

dario-piotrowicz · richardlau · commit 16b1f7a602f0 · 2025-09-20T03:32:45.000Z
add a new doc page for environment variables, this would be the one-stop place for all evnrioment variables informations (often referring to other doc pages) the main purpose of this page would also to provide a standard Node.js specification for `.env` files PR-URL: #59052 Fixes: #58807 Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -792,7 +792,7 @@ node --entry-url 'file.ts?query#hash'
 node --entry-url 'data:text/javascript,console.log("Hello")'
 ```
 
-### `--env-file-if-exists=config`
+### `--env-file-if-exists=file`
 
 <!-- YAML
 added: v22.9.0
@@ -803,7 +803,7 @@ added: v22.9.0
 Behavior is the same as [`--env-file`][], but an error is not thrown if the file
 does not exist.
 
-### `--env-file=config`
+### `--env-file=file`
 
 <!-- YAML
 added: v20.6.0
@@ -3922,8 +3922,8 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--cpu-prof-dir`]: #--cpu-prof-dir
 [`--diagnostic-dir`]: #--diagnostic-dirdirectory
 [`--disable-sigusr1`]: #--disable-sigusr1
-[`--env-file-if-exists`]: #--env-file-if-existsconfig
-[`--env-file`]: #--env-fileconfig
+[`--env-file-if-exists`]: #--env-file-if-existsfile
+[`--env-file`]: #--env-filefile
 [`--experimental-default-type=module`]: #--experimental-default-typetype
 [`--experimental-sea-config`]: single-executable-applications.md#generating-single-executable-preparation-blobs
 [`--heap-prof-dir`]: #--heap-prof-dir
diff --git a/doc/api/environment_variables.md b/doc/api/environment_variables.md
@@ -0,0 +1,156 @@
+# Environment Variables
+
+Environment variables are variables associated to the environment the Node.js process runs in.
+
+## CLI Environment Variables
+
+There is a set of environment variables that can be defined to customize the behavior of Node.js,
+for more details refer to the [CLI Environment Variables documentation][].
+
+## `process.env`
+
+The basic API for interacting with environment variables is `process.env`, it consists of an object
+with pre-populated user environment variables that can be modified and expanded.
+
+For more details refer to the [`process.env` documentation][].
+
+## DotEnv
+
+Set of utilities for dealing with additional environment variables defined in `.env` files.
+
+> Stability: 1.1 - Active development
+
+<!--introduced_in=v20.12.0-->
+
+### .env files
+
+`.env` files (also known as dotenv files) are files that define environment variables,
+which Node.js applications can then interact with (popularized by the [dotenv][] package).
+
+The following is an example of the content of a basic `.env` file:
+
+```text
+MY_VAR_A = "my variable A"
+MY_VAR_B = "my variable B"
+```
+
+This type of file is used in various different programming languages and platforms but there
+is no formal specification for it, therefore Node.js defines its own specification described below.
+
+A `.env` file is a file that contains key-value pairs, each pair is represented by a variable name
+followed by the equal sign (`=`) followed by a variable value.
+
+The name of such files is usually `.env` or it starts with `.env` (like for example `.env.dev` where
+`dev` indicates a specific target environment). This is the recommended naming scheme but it is not
+mandatory and dotenv files can have any arbitrary file name.
+
+#### Variable Names
+
+A valid variable name must contain only letters (uppercase or lowercase), digits and underscores
+(`_`) and it can't begin with a digit.
+
+More specifically a valid variable name must match the following regular expression:
+
+```text
+^[a-zA-Z_]+[a-zA-Z0-9_]*$
+```
+
+The recommended convention is to use capital letters with underscores and digits when necessary,
+but any variable name respecting the above definition will work just fine.
+
+For example, the following are some valid variable names: `MY_VAR`, `MY_VAR_1`, `my_var`, `my_var_1`,
+`myVar`, `My_Var123`, while these are instead not valid: `1_VAR`, `'my-var'`, `"my var"`, `VAR_#1`.
+
+#### Variable Values
+
+Variable values are comprised by any arbitrary text, which can optionally be wrapped inside
+single (`'`) or double (`"`) quotes.
+
+Quoted variables can span across multiple lines, while non quoted ones are restricted to a single line.
+
+Noting that when parsed by Node.js all values are interpreted as text, meaning that any value will
+result in a JavaScript string inside Node.js. For example the following values: `0`, `true` and
+`{ "hello": "world" }` will result in the literal strings `'0'`, `'true'` and `'{ "hello": "world" }'`
+instead of the number zero, the boolean `true` and an object with the `hello` property respectively.
+
+Examples of valid variables:
+
+```text
+MY_SIMPLE_VAR = a simple single line variable
+MY_EQUALS_VAR = "this variable contains an = sign!"
+MY_HASH_VAR = 'this variable contains a # symbol!'
+MY_MULTILINE_VAR = '
+this is a multiline variable containing
+two separate lines\nSorry, I meant three lines'
+```
+
+#### Spacing
+
+Leading and trailing whitespace characters around variable keys and values are ignored unless they
+are enclosed within quotes.
+
+For example:
+
+```text
+   MY_VAR_A   =    my variable a
+    MY_VAR_B   =    '   my variable b   '
+```
+
+will be treaded identically to:
+
+```text
+MY_VAR_A = my variable
+MY_VAR_B = '   my variable b   '
+```
+
+#### Comments
+
+Hash-tag (`#`) characters denote the beginning of a comment, meaning that the rest of the line
+will be completely ignored.
+
+Hash-tags found within quotes are however treated as any other standard character.
+
+For example:
+
+```text
+# This is a comment
+MY_VAR = my variable # This is also a comment
+MY_VAR_A = "# this is NOT a comment"
+```
+
+#### `export` prefixes
+
+The `export` keyword can optionally be added in front of variable declarations, such keyword will be completely ignored
+by all processing done on the file.
+
+This is useful so that the file can be sourced, without modifications, in shell terminals.
+
+Example:
+
+```text
+export MY_VAR = my variable
+```
+
+### CLI Options
+
+`.env` files can be used to populate the `process.env` object via one the following CLI options:
+
+* [`--env-file=file`][]
+
+* [`--env-file-if-exists=file`][]
+
+### Programmatic APIs
+
+There following two functions allow you to directly interact with `.env` files:
+
+* [`process.loadEnvFile`][] loads an `.env` file and populates `process.env` with its variables
+
+* [`util.parseEnv`][] parses the row content of an `.env` file and returns its value in an object
+
+[CLI Environment Variables documentation]: cli.md#environment-variables_1
+[`--env-file-if-exists=file`]: cli.md#--env-file-if-existsfile
+[`--env-file=file`]: cli.md#--env-filefile
+[`process.env` documentation]: process.md#processenv
+[`process.loadEnvFile`]: process.md#processloadenvfilepath
+[`util.parseEnv`]: util.md#utilparseenvcontent
+[dotenv]: https://github.com/motdotla/dotenv
diff --git a/doc/api/index.md b/doc/api/index.md
@@ -27,6 +27,7 @@
 * [Diagnostics Channel](diagnostics_channel.md)
 * [DNS](dns.md)
 * [Domain](domain.md)
+* [Environment Variables](environment_variables.md)
 * [Errors](errors.md)
 * [Events](events.md)
 * [File system](fs.md)
diff --git a/doc/contributing/advocacy-ambassador-program.md b/doc/contributing/advocacy-ambassador-program.md
@@ -268,7 +268,7 @@ with projects learning from one another and their users.
 | [testing source code](https://nodejs.org/api/test.html)                                               | [16.17.0](https://nodejs.org/en/blog/release/v16.17.0) | Stable as of 20.0.0                                                |
 | [watching source code](https://nodejs.org/api/cli.html#--watch)                                       | [16.19.0](https://nodejs.org/en/blog/release/v16.19.0) | Stable as of 20.13.0                                               |
 | [parsing arguments](https://nodejs.org/api/util.html#utilparseargsconfig)                             | [18.3.0](https://nodejs.org/en/blog/release/v18.3.0)   | Stable as of 20.0.0                                                |
-| [reading environment](https://nodejs.org/api/cli.html#--env-fileconfig)                               | [20.6.0](https://nodejs.org/en/blog/release/v20.6.0)   | Active Development                                                 |
+| [reading environment](https://nodejs.org/api/cli.html#--env-filefile)                                 | [20.6.0](https://nodejs.org/en/blog/release/v20.6.0)   | Active Development                                                 |
 | [styling output](https://nodejs.org/docs/latest-v22.x/api/util.html#utilstyletextformat-text-options) | [20.12.0](https://nodejs.org/en/blog/release/v20.12.0) | Stable, as of [22.13.0](https://github.com/nodejs/node/pull/56329) |
 | [run scripts](https://nodejs.org/docs/latest/api/cli.html#--run)                                      | [22.0.0](https://nodejs.org/en/blog/release/v22.0.0)   | Stable, as of 22.0.0                                               |
 | [run TypeScript](https://nodejs.org/api/cli.html#--experimental-strip-types)                          | [22.6.0](https://nodejs.org/en/blog/release/v22.6.0)   | Active Development                                                 |
@@ -281,7 +281,7 @@ with projects learning from one another and their users.
 * <https://nodejs.org/api/test.html>
 * <https://nodejs.org/api/cli.html#--watch>
 * <https://nodejs.org/api/util.html#utilparseargsconfig>
-* <https://nodejs.org/api/cli.html#--env-fileconfig>
+* <https://nodejs.org/api/cli.html#--env-filefile>
 * <https://nodejs.org/docs/latest-v22.x/api/util.html#utilstyletextformat-text-options>
 * <https://nodejs.org/api/cli.html#--run>
 * <https://nodejs.org/api/cli.html#--experimental-strip-types>
