archive/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2025-08-15 13:48:44 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

doc: add new environment variables doc page

Browse source 
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: https://github.com/nodejs/node/pull/59052
Fixes: https://github.com/nodejs/node/issues/58807
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
Dario Piotrowicz 2025-07-20 21:53:54 +01:00 • committed by GitHub
parent 3b5a5f243a
commit 0d14c954f9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 163 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

8
doc/api/cli.md
View file

@ -842,7 +842,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
@ -853,7 +853,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
@ -3980,8 +3980,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-addon-modules`]: #--experimental-addon-modules
[`--experimental-sea-config`]: single-executable-applications.md#generating-single-executable-preparation-blobs
[`--experimental-wasm-modules`]: #--experimental-wasm-modules

156
doc/api/environment_variables.md Normal file
View file

@ -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

1
doc/api/index.md
View file

@ -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)

4
doc/contributing/advocacy-ambassador-program.md
View file

@ -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>