`dotenv` not required: load `.env` and parse env vars natively in modern Node.js

dotenv is a 39 million download a week package allows Node.js apps to load environment variables from .env files and other utilities around environment variables. It’s very useful for building 12-factor apps for which a principle is to read configuration from environment variables instead of config or code files.

As of Node 20.6 (and all Node 22.x versions), env files can be loaded via the --env-file CLI argument.

As of Node.js 20.12 (and all Node 22.x versions), env files can be loaded programmatically via process.loadEnvFile() and env vars in a string can be parsed with util.parseEnv().

Note that the Node 20 release line is the Active LTS until October 2024, Node 22 is “current” until October 2024 when it becomes the Active LTS.

We’ll now detail how to use the native APIs to replace dotenv.

You can skip to the code on GitHub at: github.com/HugoDF/dotenv-not-required/, see the package.json and index.test.js.

Load an env file via CLI arguments: replace -r dotenv/config with --env-file

With dotenv:

{
  "scripts": {
    "start": "node -r dotenv/config index.js"
  }
}

With Node.js --env-file:

{
  "scripts": {
    "start": "node --env-file=.env index.js"
  }
}

Given an .env file with

MY_VAR=from-env-file

And index.js:

console.log(process.env.MY_VAR);

Running either of these via npm scripts will yield the following output:

npm start

> start
> node -r dotenv/config index.js

from-env-file

Full example available at: https://github.com/HugoDF/dotenv-not-required/blob/19daca76ce6a2059839cb4de5867c6fd067273af/package.json#L5-L6

Load an env file programmatically, replace dotenv.config() with process.loadEnvFile()

dotenv.config() can be used as follows:

dotenv.config({ path: '.env' });
// or by default path is `.env` also
dotenv.config();

This dotenv.config() call can be replaced with process.loadEnvFile(path), as follows:

import process from 'node:process';
// using the process global without this import also works
process.loadEnvFile('.env');

Full example available at: https://github.com/HugoDF/dotenv-not-required/blob/19daca76ce6a2059839cb4de5867c6fd067273af/index.test.js#L36-L52

Parse env vars from a string, replace dotenv.parse() with util.parseEnv()

dotenv.parse() is used as follows:

import dotenv from 'dotenv';

assert.deepEqual(dotenv.parse('MY_VAR=my-value'), {
  MY_VAR: 'my-value',
});

And can be replaced by the native Node.js API util.parseEnv():

import util from 'node:util';

assert.deepEqual(util.parseEnv('MY_VAR=my-value'), {
  MY_VAR: 'my-value',
});

Full example available at: https://github.com/HugoDF/dotenv-not-required/blob/19daca76ce6a2059839cb4de5867c6fd067273af/index.test.js#L54-L66

We’ve now seen how to replace dotenv.parse() with util.parseEnv and remove the need for the dotenv package.

Availability in Node.js & docs links

--env-file:

• docs for cli options
• from v20.0.6

programmatic:

• docs for process.loadEnvFile(path)
• docs for util.parseEnv(content)
• both from: v21.7.0 (so all v22), v20.12.0