diff --git a/doc/api/cli.md b/doc/api/cli.md index 2a43a489458950..2d0431b71cf6f0 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -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` + +### .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 index 7b4144639a07be..8db8b8c8806274 100644 --- 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 index e8c7936c9412b4..f58e77fc4c426d 100644 --- 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. * * * -* +* * * *