Node.js Environment Variables Management (.env)

What are environment variables (.env)? They are key-value structures that allow sensitive data such as API keys (Stripe, AWS, etc.), database passwords (PostgreSQL, MongoDB), and JWT token secrets to be safely stored separately from the source code.

The 1st rule of security in Node.js and Express.js applications is not to upload this data to version control systems like GitHub. Flyway allows you to manage these sensitive configurations directly from the panel, in a fully encrypted infrastructure.

Read Time: 6 Minutes

Security: Top Level

Scope: Node.js Frameworks

1. Prerequisites

Before configuring your Node.js environment variables, make sure you have the following:

✅ A project created on Flyway and connected with GitHub.
✅ dotenv (or @nestjs/config for NestJS) package installed in your project (For local development).

2. GitHub Security (.gitignore)

The most critical security vulnerability is accidentally uploading your locally created .env file to GitHub. A bot can scan your public repository in seconds and find your database password.

⚠️

.gitignore Rule

Be sure to add the .env line to the .gitignore file in your project's root directory. This way your passwords won't go to GitHub.

3. Adding Variables from Flyway Panel

Since you didn't commit your file to GitHub, your application will need passwords in the production environment. We safely add these via the Flyway panel.

Manage your environment variables safely via the Flyway panel.

Go to the "Environment Variables" tab from your project panel and add your Key and Value pairs.

4. Usage in Code (Main Rules)

All variables you add via the panel are transferred to the server environment while your project is compiling. You can access these variables via the process.env object inside your Node.js code.

Incorrect Usage (Hardcoded)

Writing passwords directly into the code is dangerous and requires deployment every time the code changes.

mongoose.connect('mongodb://admin:Password123@host:27017/db');

✓

Correct Usage (process.env)

Read values from environment variables.

mongoose.connect(process.env.DATABASE_URL);
const jwtSecret = process.env.JWT_SECRET;
const port = process.env.PORT || 3000;

5. Variable Reading Errors (Debugging)

If your app fails to connect to the database when deployed, 90% of the time it's due to a missing or incorrectly entered environment variable.

Go to the Flyway panel and click on the Logs tab.
If you see "Cannot read property of undefined" or "Invalid connection string" in the error log, make sure your environment variable name matches the name in the code exactly (e.g., DB_URL vs DATABASE_URL).
After adding a new environment variable, you may need to Redeploy your application.

6. Troubleshooting and FAQ

Frequently Asked Questions

Where will I upload my .env file from the Flyway panel?

Instead of uploading a file, Flyway allows you to securely add data directly via the panel in Key-Value format. You can add them one by one from the "Environment Variables" tab.

Are environment variables updated instantly?

When you add or delete a variable, the application must be restarted (Restart/Redeploy) for the changes to reflect in the Node.js process.

Troubleshooting Table (Errors and Solutions)

Error Message / Symptom	Possible Cause	Solution
process.env.VAR_NAME returns undefined	Variable not added from panel or there's a typo.	Check the variable name (case-sensitive) from the panel and redeploy.
Database connection refused	The IP address in the `DATABASE_URL` variable might not allow Flyway.	Allow external connections (or `0.0.0.0/0` IP) from your database's firewall.

Deploy Node.js (Express) →

Take your Express projects and environment variables live.

Deploy NestJS Projects →

Connect sensitive data in NestJS with the config module.

You're All Set! 🚀

Now that you're securely managing your variables, your app is ready for production. You can start serving on your Custom Domain instantly by monitoring your logs.