doc: add environment variables specification #52735
Conversation
nodejs-github-bot
added
doc
|
|
||
| 6. **Multiline values**: | ||
|
|
||
| * Values enclosed in double, single, or backtick quotes that span multiple |
There was a problem hiding this comment.
| * Values enclosed in double, single, or backtick quotes that span multiple | |
| * Values enclosed in quotes described above that span multiple |
There was a problem hiding this comment.
It may also make sense to mention that unlike shells " and ' behave identially. In shells typically ' doesn't interpolate anything, " allows inline interpolation and backticks execute a command in a subshell.
| ```cjs | ||
| const assert = require('node:assert'); | ||
| const process = require('node:process'); | ||
| assert.strictEqual(process.env.MULTI_DOUBLE_QUOTED, 'double\nquoted'); |
There was a problem hiding this comment.
You need to escape all \ characters
| assert.strictEqual(process.env.MULTI_DOUBLE_QUOTED, 'double\nquoted'); | |
| assert.strictEqual(process.env.MULTI_DOUBLE_QUOTED, 'double\\nquoted'); |
| ### Environment variables file parser specification | ||
|
|
||
| This section describes how the environment variables file parser reads a file | ||
| and sets up the environment variables in Node.js. |
There was a problem hiding this comment.
Add something about the source and how it's different like:
While
.envfiles descend from shell scripts that exported environment variables there are a few important distinctions in how they work regarding quoting, spacing and escaping values.
It may also make sense to mention the dotenv packge which popularized the format
There was a problem hiding this comment.
I have two general concerns with this PR:
-
This is a lot of text to introduce and then need to maintain; we’re essentially defining our own specification here. Is this specified somewhere already that we can just link to?
-
What happens when we want to add a new feature that’s not specified, like string interpolation? We just update this spec? Would that be a breaking change?
|
|
||
| ```bash | ||
| # COMMENTS=work | ||
| INLINE_COMMENTS=inline comments # work |
There was a problem hiding this comment.
Is the space after comments part of the value of INLINE_COMMENTS?
| This section describes how the environment variables file parser reads a file | ||
| and sets up the environment variables in Node.js. | ||
|
|
||
| 1. **Basic parsing**: |
There was a problem hiding this comment.
The docs generally avoid bold. Rather than this being a numbered list you could make subheadings:
| 1. **Basic parsing**: | |
| #### Basic parsing |
| assert.strictEqual(process.env.INLINE_COMMENTS, 'inline comments'); | ||
| ``` | ||
|
|
||
| 3. **Whitespace handling**: |
There was a problem hiding this comment.
I would list this second, above comments.
| * Any `export` keyword before a key is ignored, allowing compatibility with | ||
| shell scripts. |
There was a problem hiding this comment.
I initially read this as saying that any lines beginning with export get ignored, not that just the export keyword alone is ignored.
| * Any `export` keyword before a key is ignored, allowing compatibility with | |
| shell scripts. | |
| * Any `export` keyword before a key is ignored, allowing compatibility with | |
| shell scripts. The line is parsed as if `export` wasn't there. |
Following #49148
Add documentation for environment variables specifications