How to Use Environment Variables in Node.js

Environment variables are values provided to your application by the operating system at runtime rather than being hardcoded in your source code. They allow the same codebase to connect to different databases, use different API keys, and behave differently in development versus production without any code changes. They also keep secrets out of version control.

Node.js exposes all environment variables as properties on the process.env object. If an environment variable named DATABASE_URL is set in the operating system, you can read it inside your code with process.env.DATABASE_URL. The value is always a string, so parse it with parseInt or JSON.parse when you need a number or boolean.

Install the dotenv package from npm. Create a .env file in the root of your project. Call require('dotenv').config() or import and call config from dotenv at the very top of your application entry point before any other code runs. dotenv reads the .env file and loads each line as a key-value pair into process.env.

Write each environment variable on its own line in the format KEY=value with no spaces around the equals sign. Do not use quotes around values unless the value itself contains spaces or special characters. Use uppercase names with underscores as separators by convention. Group related variables together and add comments using lines starting with a hash symbol.

The moment you create a .env file, add it to your .gitignore file. This prevents Git from ever tracking or committing the file. Committing secrets like database passwords or API keys to a repository, even a private one, is a serious security risk. Create a .env.example file with the same keys but empty values and commit that instead as documentation for other developers.

If your application starts without a required environment variable, it will fail later in an unpredictable way. Validate all required environment variables at the very start of your application before doing anything else. Check each required variable and if any are missing or empty, log a clear error message listing all missing variables and call process.exit(1) to stop the application immediately.

Create separate environment files for different environments such as .env.development and .env.production. Configure your start scripts to load the appropriate file based on the NODE_ENV variable. Libraries like dotenv-flow or envalid handle this automatically. In production, most platforms like AWS, Heroku, and Vercel provide their own environment variable management interfaces instead of .env files.

Avoid logging the entire process.env object or individual secret values anywhere in your application, including during startup or debugging. If your logs are stored externally or accidentally exposed, every secret becomes compromised. Log only non-sensitive configuration values like the port number or the current environment name to confirm the application started with the right configuration.