|
| 1 | +# Environment Variables |
| 2 | + |
| 3 | +Environment variables are variables associated to the environment the Node.js process runs in. |
| 4 | + |
| 5 | +## CLI Environment Variables |
| 6 | + |
| 7 | +There is a set of environment variables that can be defined to customize the behavior of Node.js, |
| 8 | +for more details refer to the [CLI Environment Variables documentation][]. |
| 9 | + |
| 10 | +## `process.env` |
| 11 | + |
| 12 | +The basic API for interacting with environment variables is `process.env`, it consists of an object |
| 13 | +with pre-populated user environment variables that can be modified and expanded. |
| 14 | + |
| 15 | +For more details refer to the [`process.env` documentation][]. |
| 16 | + |
| 17 | +## DotEnv |
| 18 | + |
| 19 | +Set of utilities for dealing with additional environment variables defined in `.env` files. |
| 20 | + |
| 21 | +> Stability: 1.1 - Active development |
| 22 | +
|
| 23 | +<!--introduced_in=v20.12.0--> |
| 24 | + |
| 25 | +### .env files |
| 26 | + |
| 27 | +`.env` files (also known as dotenv files) are files that define environment variables, |
| 28 | +which Node.js applications can then interact with (popularized by the [dotenv][] package). |
| 29 | + |
| 30 | +The following is an example of the content of a basic `.env` file: |
| 31 | + |
| 32 | +```text |
| 33 | +MY_VAR_A = "my variable A" |
| 34 | +MY_VAR_B = "my variable B" |
| 35 | +``` |
| 36 | + |
| 37 | +This type of file is used in various different programming languages and platforms but there |
| 38 | +is no formal specification for it, therefore Node.js defines its own specification described below. |
| 39 | + |
| 40 | +A `.env` file is a file that contains key-value pairs, each pair is represented by a variable name |
| 41 | +followed by the equal sign (`=`) followed by a variable value. |
| 42 | + |
| 43 | +The name of such files is usually `.env` or it starts with `.env` (like for example `.env.dev` where |
| 44 | +`dev` indicates a specific target environment). This is the recommended naming scheme but it is not |
| 45 | +mandatory and dotenv files can have any arbitrary file name. |
| 46 | + |
| 47 | +#### Variable Names |
| 48 | + |
| 49 | +A valid variable name must contain only letters (uppercase or lowercase), digits and underscores |
| 50 | +(`_`) and it can't begin with a digit. |
| 51 | + |
| 52 | +More specifically a valid variable name must match the following regular expression: |
| 53 | + |
| 54 | +```text |
| 55 | +^[a-zA-Z_]+[a-zA-Z0-9_]*$ |
| 56 | +``` |
| 57 | + |
| 58 | +The recommended convention is to use capital letters with underscores and digits when necessary, |
| 59 | +but any variable name respecting the above definition will work just fine. |
| 60 | + |
| 61 | +For example, the following are some valid variable names: `MY_VAR`, `MY_VAR_1`, `my_var`, `my_var_1`, |
| 62 | +`myVar`, `My_Var123`, while these are instead not valid: `1_VAR`, `'my-var'`, `"my var"`, `VAR_#1`. |
| 63 | + |
| 64 | +#### Variable Values |
| 65 | + |
| 66 | +Variable values are comprised by any arbitrary text, which can optionally be wrapped inside |
| 67 | +single (`'`) or double (`"`) quotes. |
| 68 | + |
| 69 | +Quoted variables can span across multiple lines, while non quoted ones are restricted to a single line. |
| 70 | + |
| 71 | +Noting that when parsed by Node.js all values are interpreted as text, meaning that any value will |
| 72 | +result in a JavaScript string inside Node.js. For example the following values: `0`, `true` and |
| 73 | +`{ "hello": "world" }` will result in the literal strings `'0'`, `'true'` and `'{ "hello": "world" }'` |
| 74 | +instead of the number zero, the boolean `true` and an object with the `hello` property respectively. |
| 75 | + |
| 76 | +Examples of valid variables: |
| 77 | + |
| 78 | +```text |
| 79 | +MY_SIMPLE_VAR = a simple single line variable |
| 80 | +MY_EQUALS_VAR = "this variable contains an = sign!" |
| 81 | +MY_HASH_VAR = 'this variable contains a # symbol!' |
| 82 | +MY_MULTILINE_VAR = ' |
| 83 | +this is a multiline variable containing |
| 84 | +two separate lines\nSorry, I meant three lines' |
| 85 | +``` |
| 86 | + |
| 87 | +#### Spacing |
| 88 | + |
| 89 | +Leading and trailing whitespace characters around variable keys and values are ignored unless they |
| 90 | +are enclosed within quotes. |
| 91 | + |
| 92 | +For example: |
| 93 | + |
| 94 | +```text |
| 95 | + MY_VAR_A = my variable a |
| 96 | + MY_VAR_B = ' my variable b ' |
| 97 | +``` |
| 98 | + |
| 99 | +will be treaded identically to: |
| 100 | + |
| 101 | +```text |
| 102 | +MY_VAR_A = my variable |
| 103 | +MY_VAR_B = ' my variable b ' |
| 104 | +``` |
| 105 | + |
| 106 | +#### Comments |
| 107 | + |
| 108 | +Hash-tag (`#`) characters denote the beginning of a comment, meaning that the rest of the line |
| 109 | +will be completely ignored. |
| 110 | + |
| 111 | +Hash-tags found within quotes are however treated as any other standard character. |
| 112 | + |
| 113 | +For example: |
| 114 | + |
| 115 | +```text |
| 116 | +# This is a comment |
| 117 | +MY_VAR = my variable # This is also a comment |
| 118 | +MY_VAR_A = "# this is NOT a comment" |
| 119 | +``` |
| 120 | + |
| 121 | +#### `export` prefixes |
| 122 | + |
| 123 | +The `export` keyword can optionally be added in front of variable declarations, such keyword will be completely ignored |
| 124 | +by all processing done on the file. |
| 125 | + |
| 126 | +This is useful so that the file can be sourced, without modifications, in shell terminals. |
| 127 | + |
| 128 | +Example: |
| 129 | + |
| 130 | +```text |
| 131 | +export MY_VAR = my variable |
| 132 | +``` |
| 133 | + |
| 134 | +### CLI Options |
| 135 | + |
| 136 | +`.env` files can be used to populate the `process.env` object via one the following CLI options: |
| 137 | + |
| 138 | +* [`--env-file=file`][] |
| 139 | + |
| 140 | +* [`--env-file-if-exists=file`][] |
| 141 | + |
| 142 | +### Programmatic APIs |
| 143 | + |
| 144 | +There following two functions allow you to directly interact with `.env` files: |
| 145 | + |
| 146 | +* [`process.loadEnvFile`][] loads an `.env` file and populates `process.env` with its variables |
| 147 | + |
| 148 | +* [`util.parseEnv`][] parses the row content of an `.env` file and returns its value in an object |
| 149 | + |
| 150 | +[CLI Environment Variables documentation]: cli.md#environment-variables_1 |
| 151 | +[`--env-file-if-exists=file`]: cli.md#--env-file-if-existsfile |
| 152 | +[`--env-file=file`]: cli.md#--env-filefile |
| 153 | +[`process.env` documentation]: process.md#processenv |
| 154 | +[`process.loadEnvFile`]: process.md#processloadenvfilepath |
| 155 | +[`util.parseEnv`]: util.md#utilparseenvcontent |
| 156 | +[dotenv]: https://github.com/motdotla/dotenv |
0 commit comments