DEV Community

Dotenv
Dotenv

Posted on • Originally published at dotenv.org on

Node.js 20.6.0 includes built-in support for .env files

#dotenv #secrets #devops

Node v20.6.0+ adds native support for loading .env files.

node --env-file=.env index.js
Enter fullscreen mode Exit fullscreen mode

Wow, cool!

Is dotenv dead? Stop using it? Not so fast. Don’t drop dotenv just yet. There are some caveats you should know first.

First, let me say, it is great to see the NodeJS team adopt first-class .env support for developers. As one of the pioneers of dotenv, it’s an honor. dotenv is depended on by more than 14 Million open source repos on GitHub alone and downloaded more than 35 Million times per week. dotenv has proven itself as a trusty friend to millions of developers worldwide.

Anyways, let’s see how this built-in support works (or skip to the caveats section).

Find a complete code example on GitHub for this blog post.

How it works

Install Node v20.6.0 or greater using nvm.

nvm install 20.6.0
nvm use 20.6.0
node -v
v20.6.0
Enter fullscreen mode Exit fullscreen mode

Create your .env file.

HELLO="World"
Enter fullscreen mode Exit fullscreen mode

Create your node script to make use of it.

// index.js
console.log(`Hello ${process.env.HELLO}`)
Enter fullscreen mode Exit fullscreen mode

Run it with the --env-file flag.

node --env-file=.env index.js
Hello World
Enter fullscreen mode Exit fullscreen mode

That’s it!

Want to run it in production? Just point it to a .env.production file.

# .env.production
HELLO="production"
Enter fullscreen mode Exit fullscreen mode 
node --env-file=.env.production index.js
Enter fullscreen mode Exit fullscreen mode

Caveats

The biggest current caveat is that this is still an experimental feature. That means it will ship with bugs and with missing feature support. The top hn comment sums it up well - albeit a bit grumpily.

I also want stress the word current because this is all still under active development. These things take time. By the time you read this, some of these caveats might no longer be around.

Missing multiline support

The current implementation does not support multiline environment variables. If you attempt to include a multiline environment variable it will be undefined. For example:

# .env.multiline
HELLO="This
is
a
multiline"
Enter fullscreen mode Exit fullscreen mode 
// index.js
console.log(`Hello ${process.env.HELLO}`)
Enter fullscreen mode Exit fullscreen mode 
node --env-file=.env.multiline index.js
Hello undefined
Enter fullscreen mode Exit fullscreen mode

Note: multiline support is being actively discussed and will probably get added in the near future.

Missing override option

You cannot override your system’s environment variables with your .env file. There is no option.

# .env
HELLO="World"
Enter fullscreen mode Exit fullscreen mode 
// index.js
console.log(`Hello ${process.env.HELLO}`)
Enter fullscreen mode Exit fullscreen mode 
export HELLO="System"
node --env-file=.env index.js
Hello System
Enter fullscreen mode Exit fullscreen mode

It prints Hello System rather then Hello World. There is no option to overwrite system variables.

If you need to do this then continue using dotenv with its override option.

Missing variable expansion

It’s important to note that variable expansion support has always existed in a separate library dotenv-expand. But it is so widely used with 13 million downloads that it defacto considered part of dotenv.

As of this writing, Node does not support variable expansion. Instead, it will output the variable as a string.

# .env
PASSWORD="password123"
SECRET=$PASSWORD
Enter fullscreen mode Exit fullscreen mode 
// index.js
console.log(`The secret is ${process.env.SECRET}`)
Enter fullscreen mode Exit fullscreen mode 
node --env-file=.env index.js
The secret is $PASSWORD
Enter fullscreen mode Exit fullscreen mode

So if you need variable expansion, you should continue using dotenv and dotenv-expand.

Missing .env.vault support

The .env.vault file is the spiritual successor to the .env file. They have multiple security advantages which you can read about here.

They are quite new but also quite useful for production and ci. They are gaining adoption across multiple languages like python and rust. dotenv supports them but Node’s implementation of .env files does not at this time.

#/-------------------.env.vault---------------------/
#/ cloud-agnostic vaulting standard /
#/ [how it works](https://dotenv.org/env-vault) /
#/--------------------------------------------------/
# development
DOTENV_VAULT_DEVELOPMENT="AtEC33ZfFJQMSE6C+EBX8nzTyQzfC+xhsIfGjyWr47jiHsUi07PHzX2/RmCB0PIi"
# production
DOTENV_VAULT_PRODUCTION="t9van8HefnTIHVlK3vQ6WYLtWEOvPunEnOphV3Hw3aBTBDuwLq22yU0Tdl5fAnk="
Enter fullscreen mode Exit fullscreen mode

Conclusion

In conclusion, built-in support for .env files (even if currently experimental) is a huge and welcome step forward for Node. We should particularly thank Yagiz Nizipli for making this happen. Go sponsor him on GitHub. He is doing incredible work for Node.

That said, there are some caveats, and I would recommend against npm uninstall-ing dotenv for your production apps at this time. Wait until it is non-experimental and has added support for the missing features above.

Using .env files?

dotenv-vault is a secrets manager for securely managing them. Create your Dotenv Account and try it today.

https://dotenv.org/signup

Top comments (0)

Read next

jorgetovar profile image

Provisioned Concurrency - Reduce Cold Starts in AWS Lambda Functions Part 1

Jorge Tovar -

mochafreddo profile image

Preventing and Solving Husky Permission Denied Errors in Node.js Projects

Geoffrey Kim -

storybookjs profile image

Storybook 8

Storybook -

thenjdevopsguy profile image

Running Stormforge with Karpenter and Kubecost

Michael Levan -