A Modest Flag for the Local Secret

Most developers act as if npm install dotenv is a required ritual, like saying "bless you" after a sneeze. It’s the first thing we do. We initialize a project, we git-ignore .env, and we immediately reach for an external package just to read a few strings from a text file. For over a decade, this was the "standard" way to handle local secrets. But frankly, it’s a bit silly to add a dependency—and all the supply-chain baggage that comes with it—for a task as simple as parsing a key-value pair.

Since the release of Node.js v20.6.0, the ritual is officially dead. Node now handles .env files natively, and it does so with a single, modest flag.

The End of the Dotenv Ritual

I’ve always felt a slight twinge of guilt every time I looked at a package.json and saw dotenv sitting there. It’s a great library, don't get me wrong, but it feels like bringing a chainsaw to cut a sandwich. You have to import it, call .config(), and make sure it’s loaded before any other module that might need those environment variables.

Here is the "old" way we’ve all written a thousand times:

// index.js
require('dotenv').config();

const dbUrl = process.env.DATABASE_URL;
console.log(`Connecting to: ${dbUrl}`);

It works, but it's intrusive. Your code now has to know about your environment variable loader. If you forget to put that require at the absolute top of your entry point, things break in ways that are annoying to debug.

Enter the Flag

The native Node.js way is cleaner because it happens outside the code. You don't have to change a single line of your JavaScript. You just tell the runtime where the secrets are kept.

node --env-file=.env index.js

That’s it. Node reads the file, parses the variables, and populates process.env before your script even starts breathing. Your code becomes "environment agnostic," which is exactly what it should be.

Handling Multiple Files

In the real world, we often have layers of configuration. Maybe a base .env for defaults and a .env.local for your specific machine. Node handles this by letting you pass the flag multiple times.

node --env-file=.env --env-file=.env.local server.js

Note: If you have the same key in both files, the last one wins. This is perfect for overriding generic settings with local overrides.

Programmatic Loading (for the control freaks)

Sometimes, you *do* want to load secrets based on logic inside your app—maybe based on a --stage argument or an existing environment variable. In Node.js v21.7.0, they added a programmatic way to do this without using the CLI flag, effectively replacing the dotenv API entirely.

import { loadEnvFile } from 'node:process';

// This loads the default .env file
loadEnvFile();

// Or specify a path
loadEnvFile('./config/.env.dev');

console.log(process.env.API_KEY);

If you just need to parse a string that looks like a .env file without actually dumping it into process.env, there’s even a utility for that now in the util module:

import { parseEnv } from 'node:util';

const rawConfig = `PORT=3000\nTHEME=dark`;
const config = parseEnv(rawConfig);

console.log(config.PORT); // "3000"

The "Gotchas" and Edge Cases

It’s not all sunshine and rainbows. The native loader is a bit more opinionated (read: strict) than the dotenv package.

1. Multiline Values: The native parser handles basic quoted strings, but if you have complex multiline RSA keys, it can occasionally be finicky compared to the battle-tested dotenv.
2. Variable Expansion: If you’re used to dotenv-expand (e.g., PORT=${BASE_PORT}), the native Node.js loader doesn't support this out of the box. It treats the value as a literal string.
3. Version Matters: This isn't an option if you're stuck on an old LTS version like Node 16 or 18. You need at least 20.6.0 for the flag and 21.7.0 for the programmatic methods.

Why this actually matters

Dependency bloat is the cholesterol of the development world. Each small package we add seems harmless, but they accumulate. By using the built-in --env-file flag, you:

* Reduce your attack surface: One less package to potentially contain a malicious update.
* Speed up installs: It’s one less thing for npm install to fetch and check.
* Simplify Dockerfiles: You no longer need to worry if devDependencies were pruned correctly; the functionality is just *there* in the runtime.

Next time you’re starting a Node.js project, resist the urge to npm install dotenv. Try the modest flag instead. Your node_modules folder—and your future self—will thank you.