How to set environment variables in Node.js

Modern software demands flexibility, scalability, and robust security. Environment variables play a vital role in achieving this balance. This guide explores various methods for setting and managing environment variables within Node.js applications, emphasizing best practices for security and maintainability. We'll cover everything from startup validation to preventing sensitive data exposure. Whether you're a seasoned developer or new to Node.js, this information is essential for building secure, adaptable applications.

What are Environment Variables?

Environment variables are key-value pairs stored outside your application's codebase, typically in configuration files or system settings. They hold sensitive data like API keys and database credentials, preventing hardcoding and improving security. This approach simplifies management across different environments (development, testing, production).

In Node.js, environment variables enable dynamic application configuration without code modification. The same codebase can interact with different databases or APIs depending on the environment, enhancing security, simplifying deployment, and boosting adaptability.

Unlike standard JavaScript variables, environment variables are not defined within the code. They're accessed via process.env and exist independently, potentially influencing multiple applications on the system.

Accessing Environment Variables in Node.js

Node.js uses the process.env object to access and manage environment variables. To retrieve a variable's value, use process.env.VARIABLE_NAME. For example, process.env.API_KEY retrieves the value associated with API_KEY. While technically possible to set environment variables within code, this is generally discouraged; it negates the benefits of using environment variables in the first place.

Here's how API_KEY might be used in an Express API:

const express = require('express');
const app = express();

// Access API key from environment variables
const apiKey = process.env.API_KEY;

if (!apiKey) {
  console.error('Error: API key is not defined.');
  process.exit(1);
}

app.get('/', (req, res) => {
  res.send('API key successfully loaded.');
});

// Start the server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Setting Environment Variables in Node.js

Now, let's explore different methods for setting environment variables:

1. Using dotenv: The dotenv package simplifies managing environment variables by separating them from your code. Define key-value pairs in a .env file:

<code>PORT=3000
DB_USERNAME=dbuser</code>

Import and use it like this:

import * as dotenv from 'dotenv';
dotenv.config();

console.log(process.env.PORT); // Output: 3000
console.log(process.env.DB_USERNAME); // Output: dbuser

You can specify alternative .env file paths using dotenv.config({ path: './path/to/another.env' }). While useful for development, consider other methods for production.

2. System-Level Setting: On Unix-like systems (Linux, macOS), add variables to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc). This affects all processes in that shell session. For example:

const express = require('express');
const app = express();

// Access API key from environment variables
const apiKey = process.env.API_KEY;

if (!apiKey) {
  console.error('Error: API key is not defined.');
  process.exit(1);
}

app.get('/', (req, res) => {
  res.send('API key successfully loaded.');
});

// Start the server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Restart your terminal or run source ~/.bashrc to apply changes. For system-wide access (system processes), use /etc/environment.

3. Launch Script: Create a script that sets variables and then runs your Node.js application (e.g., launch.sh):

<code>PORT=3000
DB_USERNAME=dbuser</code>

Make it executable (chmod x launch.sh) and run it (./launch.sh).

4. PM2 (Process Manager 2): PM2 allows setting environment variables during application startup:

import * as dotenv from 'dotenv';
dotenv.config();

console.log(process.env.PORT); // Output: 3000
console.log(process.env.DB_USERNAME); // Output: dbuser

Or use an ecosystem.config.js file for environment-specific configurations.

5. Docker: In Docker, set variables in the Dockerfile using ENV:

# ~/.bashrc
export PORT=3000
export DB_USERNAME=myuser

Override defaults when running the container using -e PORT=5173 or within a docker-compose.yml file.

Best Practices for Using Environment Variables

Follow these best practices for secure and maintainable applications:

• Descriptive Names and Documentation: Use clear, descriptive names and document their purpose in your project's README.

• Startup Validation: Validate environment variables at application startup to ensure they're set correctly. Handle missing variables gracefully (default values or error handling).

• .env File Exclusion: Exclude .env files from version control (Git) using .gitignore.

• Consider a KMS (Key Management System): For enhanced security, especially with highly sensitive data, use a KMS to encrypt and store your environment variables.

• Default Values: Provide default values for non-critical environment variables to ensure application functionality even if variables are missing.

• Never Expose in the Frontend: Never expose sensitive environment variables directly to the client-side code.

Clerk's Use of Environment Variables

Clerk SDKs utilize environment variables for configuration and application association within the Clerk dashboard. This enables secure backend requests and frontend validation using Express. For example:

#!/bin/bash
export PORT=3000
export DB_USERNAME=myuser
node app.js

Conclusion

Securely managing environment variables is paramount. By following these best practices, you'll significantly enhance the security and maintainability of your Node.js applications, ensuring they're ready for production deployment.

The above is the detailed content of How to set environment variables in Node.js. For more information, please follow other related articles on the PHP Chinese website!