Effortlessly Load Environment Variables in package.json Scripts with dotenv

Why Load Environment Variables in Your package.json Scripts?

If you’ve ever developed a Node.js or TypeScript application, you’re probably familiar with environment variables. These are essential for managing sensitive information, such as API keys and database credentials, without hardcoding them into your code. While using .env files to store these variables is common practice, ensuring they load correctly when running scripts from package.json can be a bit tricky.

Thank me by sharing on Twitter 🙏

For example, if you’re running a TypeScript project, you might have a script like "dev": "tsx watch src/index.ts", which starts the TypeScript watcher. But without loading environment variables, your app might fail to run or operate without access to key information. By integrating dotenv directly into these scripts, we can make sure all required variables are loaded smoothly, right before each script runs. Here’s how I set it up.

How to Set Up dotenv in Your package.json Scripts

Let’s dive in and set this up step-by-step.

Step 1: Install dotenv-cli

To load environment variables easily, I’m using a package called dotenv-cli, which extends the power of dotenv to our command-line scripts. To install it, run:

npm install dotenv-cli --save-dev

This package lets us specify .env files directly in our scripts, ensuring the variables load before the main command starts.

SanDisk 256GB Extreme microSDXC UHS-I Memory Card with Adapter - Up to 190MB/s, C10, U3, V30, 4K, 5K, A2, Micro SD Card - SDSQXAV-256G-GN6MA

(109193)

$24.99 (as of January 9, 2025 10:16 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

TAKAGI for iPhone Charger, [MFi Certified] Lightning Cable 3PACK 6FT Nylon Braided USB Charging Cable High Speed Transfer Cord Compatible with iPhone 14/13/12/11 Pro Max/XS MAX/XR/XS/X/8/iPad

(112975)

$9.99 (as of January 9, 2025 10:16 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

HP 63 Black Ink Cartridge | Works with HP DeskJet 1112, 2130, 3630 Series; HP ENVY 4510, 4520 Series; HP OfficeJet 3830, 4650, 5200 Series | Eligible for Instant Ink | F6U62AN

(92099)

$24.89 (as of January 9, 2025 10:16 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

Step 2: Add dotenv to Your package.json Script

In package.json, locate the scripts section. I wanted to load my environment variables before starting the TypeScript watcher, so I edited the script as follows:

{
  "scripts": {
    "dev": "dotenv -e .env -- tsx watch src/index.ts"
  }
}

This command does two things:

1. dotenv -e .env -- loads the variables from .env.
2. tsx watch src/index.ts starts the TypeScript watcher, with access to any environment variables loaded by dotenv.

Step 3 (Optional): For Cross-Platform Compatibility, Use cross-env

Some setups require additional compatibility, especially on Windows. By adding cross-env, I can ensure compatibility across different environments.

To install cross-env, run:

npm install cross-env --save-dev

Then, update the script as follows:

{
  "scripts": {
    "dev": "cross-env $(dotenv -e .env) tsx watch src/index.ts"
  }
}

This allows the script to load environment variables in a way that’s compatible with both Windows and Unix-based systems.

Conclusion

Integrating dotenv-cli into your package.json scripts makes loading environment variables quick and hassle-free. Now, whenever I run npm run dev, my .env variables are automatically loaded, keeping my sensitive data secure and my code clean. This setup saves time and avoids issues with missing environment variables, so I can focus on building features instead of troubleshooting configuration.

Give this approach a try and see how it simplifies your workflow!