dotenvx
.env
The .env
file separates your secrets from code. Here is what it looks like.
.env
# .env
STRIPE_API_KEY=scr_12345
TWILIO_API_KEY=abcd1234
It's a simple format – key/value separated by an equal sign. You can additionally include comments.
Then it is loaded into your application code using process.env
.
console.log('Hello ' + process.env.HELLO)
This way your secrets – like your Stripe API key – are not commited to your code.
By separating your secrets from your code (your .env
file is not commited to source control), you improve your security posture. If your code leaks, your secrets (like your Stripe API key) are less likely to be at risk.
Variable Names
For the sake of portability (and sanity), environment variable names must consist solely of letters, digits, and the underscore ( _
) and must not begin with a digit. In regex-speak, the names must match the following pattern:
[a-zA-Z_]+[a-zA-Z0-9_]*
Example variable names
DATABASE_URL # ok
foobar # ok (but not recommended. use upcase)
NO-WORK # <-- invalid !!!
ÜBER # <-- invalid !!!
2MUCH # <-- invalid !!!
Values
Values are to the right of the equals sign. They may be quoted. Using single quotes will prevent variables from being interpolated.
SIMPLE=xyz123
INTERPOLATED="Multiple\nLines"
NON_INTERPOLATED='raw text without variable interpolation'
MULTILINE = `long text here,
e.g. a private SSH key`
Comments
The hash-tag #
symbol denotes a comment when on its own line or when it follows a quoted value. It is not treated as a comment when it appears within quotes.
# This is a comment
SECRET_KEY=YOURSECRETKEYGOESHERE # also a comment
SECRET_HASH="something-with-a-hash-#-this-is-not-a-comment"
Syntax
The following syntax rules apply to environment files:
- Lines beginning with
#
are processed as comments and ignored. - Blank lines are ignored.
- Unquoted and double-quoted (
"
) values have interpolation applied. - Each line represents a key-value pair. Values can optionally be quoted.
VAR=VAL
->VAL
VAR="VAL"
->VAL
VAR='VAL'
->VAL
- Inline comments for unquoted values must be preceded with a space.
VAR=VAL # comment
->VAL
VAR=VAL# not a comment
->VAL# not a comment
- Inline comments for quoted values must follow the closing quote.
VAR="VAL # not a comment"
->VAL # not a comment
VAR="VAL" # comment
->VAL
- Single-quoted (') values are used literally.
VAR='$OTHER'
->$OTHER
VAR='${OTHER}'
->${OTHER}
- Quotes can be escaped with .
VAR='Let\'s go!'
->Let's go!
VAR="{\"hello\": \"json\"}"
->{"hello": "json"}
- Common shell escape sequences including
\n
,\r
,\t
, and\\
are supported in double-quoted values.VAR="some\tvalue"
->some value
VAR='some\tvalue'
->some\tvalue
VAR=some\tvalue
->some\tvalue
Interpolation
Interpolation (substitution) is supported in environment files. Interpolation is applied for unquoted and double-quoted values. Both braced (${VAR}
) and unbraced ($VAR
) expressions are supported.
- Direct substitution
${VAR}
-> value ofVAR
- Default value
${VAR:-default}
-> value ofVAR
if set and non-empty, otherwisedefault
${VAR-default}
-> value ofVAR
if set, otherwisedefault
History
The .env
file format was introduced by Heroku in 2012 and popularized by the dotenv node and dotenv ruby libraries in 2013.
Apps sometimes store config as constants in the code. This is a violation of twelve-factor, which requires strict separation of config from code. Config varies substantially across deploys, code does not.
A litmus test for whether an app has all config correctly factored out of the code is whether the codebase could be made open source at any moment, without compromising any credentials. The Twelve-Factor App
Other languages, frameworks, platforms, and infra tools like Docker followed soon after – implementing environment variable support. Today, it has become an industry standard.