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