Environment variables in NestJS - Deep Dive

Overview - Environment variables

What is it?

Environment variables are special settings stored outside your code that tell your application how to behave. They hold important information like passwords, API keys, or configuration options. Instead of hardcoding these details, environment variables keep them separate and easy to change without touching the code. This helps keep your app safe and flexible.

Why it matters

Without environment variables, sensitive information would be mixed directly in the code, risking security leaks and making updates hard. Imagine having to change your password inside every file whenever it changes! Environment variables let you change settings quickly and keep secrets safe, which is crucial for apps running in different places like your computer, a test server, or the internet.

Where it fits

Before learning environment variables, you should understand basic NestJS app structure and configuration. After this, you can explore advanced configuration management, secrets handling, and deployment practices. Environment variables are a key step between writing code and running it safely in real-world environments.

Mental Model

Core Idea

Environment variables are like secret notes you keep outside your app’s code that tell it important details without exposing them directly.

Think of it like...

Think of environment variables like the settings on your phone that control brightness or volume. You don’t change the phone’s software to adjust these; you just tweak the settings. Similarly, environment variables let you change app behavior without changing the app itself.

┌─────────────────────┐
│  Environment File   │
│  (.env)             │
│  KEY=VALUE          │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  NestJS Application  │
│  Reads variables     │
│  from environment    │
└─────────────────────┘

Build-Up - 6 Steps

1

Foundation

What are environment variables

Concept: Introduce the basic idea of environment variables as external settings for apps.

Environment variables are key-value pairs stored outside your code. They provide information like database URLs, API keys, or modes (development or production). Instead of writing these details inside your code files, you keep them in a separate place so you can change them anytime without touching the code.

Result

You understand that environment variables hold important info outside your code to keep it flexible and secure.

Understanding that environment variables separate configuration from code helps you keep apps safe and easy to update.

2

Foundation

Using .env files in NestJS

Concept: Learn how to store environment variables in a .env file and load them in NestJS.

Create a file named .env in your project root. Inside, write lines like DATABASE_URL=your_database_url. NestJS can load these variables using the ConfigModule. This module reads the .env file and makes the variables available in your app.

Result

Your NestJS app can access environment variables from the .env file using ConfigService.

Knowing how to load .env files lets you manage settings easily without changing code.

3

Intermediate

Accessing variables with ConfigService

🤔Before reading on: do you think you access environment variables directly or through a service in NestJS? Commit to your answer.

Concept: Use NestJS's ConfigService to safely access environment variables inside your code.

NestJS provides ConfigService from @nestjs/config. Inject it into your classes to get variables by calling configService.get('VARIABLE_NAME'). This avoids using process.env directly and adds type safety and validation.

Result

You can get environment variables inside your services or controllers using ConfigService methods.

Using ConfigService instead of process.env improves code safety and makes testing easier.

4

Intermediate

Validating environment variables

🤔Before reading on: do you think environment variables are always correct or should be checked? Commit to your answer.

Concept: Add validation to ensure environment variables have correct values before app starts.

Use Joi or similar libraries with ConfigModule to define a schema for expected variables. NestJS will check the .env values against this schema and throw errors if something is missing or wrong. This prevents bugs caused by bad or missing config.

Result

Your app will fail early with clear errors if environment variables are invalid or missing.

Validating environment variables prevents hard-to-find bugs and improves app reliability.

5

Advanced

Using multiple environment files

🤔Before reading on: do you think one .env file is enough for all environments? Commit to your answer.

Concept: Manage different environment variables for development, testing, and production using multiple .env files.

Create files like .env.development, .env.test, .env.production with different values. Configure ConfigModule to load the right file based on NODE_ENV variable. This lets you switch settings automatically depending on where your app runs.

Result

Your app uses environment-specific settings without manual changes, improving deployment safety.

Using multiple .env files helps keep environments isolated and reduces risk of leaking test or dev settings to production.

6

Expert

Security and best practices for environment variables

🤔Before reading on: do you think environment variables are always secure or can they leak? Commit to your answer.

Concept: Understand the security risks and best ways to handle environment variables in production.

Never commit .env files with secrets to version control. Use secret managers or environment-specific injection in deployment pipelines. Limit access to environment variables on servers. Avoid logging sensitive variables. Use ConfigService carefully to prevent accidental exposure.

Result

Your app keeps secrets safe and follows industry best practices for configuration security.

Knowing environment variable security prevents leaks that can cause data breaches or service outages.

Under the Hood

At runtime, the operating system or container injects environment variables into the process running the NestJS app. The ConfigModule reads these variables from process.env or .env files loaded into memory. ConfigService provides a layer to access these variables safely inside the app. Validation schemas check values before app initialization to catch errors early.

Why designed this way?

Environment variables were designed to separate configuration from code, allowing the same code to run in different environments without changes. This design supports security by keeping secrets out of code repositories and flexibility by enabling quick config changes. Alternatives like hardcoding or config files inside code were less secure and less flexible.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Operating     │       │ NestJS        │       │ Your Code     │
│ System/Host   │──────▶│ ConfigModule  │──────▶│ Uses Config   │
│ Injects       │       │ Loads .env or │       │ Service to    │
│ environment   │       │ process.env   │       │ get variables │
│ variables     │       └───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think environment variables are automatically secure and private? Commit to yes or no.

Common Belief: Environment variables are always safe because they are outside the code.

Reality: Environment variables can be exposed if .env files are committed to public repos or if server access is not restricted.

Why it matters: Assuming environment variables are secure can lead to accidental leaks of passwords or keys, causing security breaches.

Quick: Do you think you can change environment variables while the app is running and it will update automatically? Commit to yes or no.

Common Belief: Changing environment variables on the server instantly changes app behavior without restart.

Reality: Environment variables are loaded when the app starts; changes require restarting the app to take effect.

Why it matters: Expecting live updates can cause confusion and bugs if the app continues using old values.

Quick: Do you think accessing environment variables directly via process.env is the best practice in NestJS? Commit to yes or no.

Common Belief: Using process.env directly is fine and recommended for simplicity.

Reality: NestJS encourages using ConfigService for better type safety, validation, and testability.

Why it matters: Direct access can lead to scattered code, harder testing, and missed validation opportunities.

Quick: Do you think one .env file is enough for all environments like development and production? Commit to yes or no.

Common Belief: A single .env file can hold all environment variables for every environment.

Reality: Different environments need separate .env files to avoid mixing sensitive or incompatible settings.

Why it matters: Using one file risks deploying wrong settings, causing failures or security issues.

Expert Zone

1

ConfigModule supports caching loaded environment variables to improve performance in large apps.

2

You can extend ConfigService with custom validation and transformation logic for complex config needs.

3

Environment variables are strings by default; converting them to numbers or booleans requires explicit parsing.

When NOT to use

Environment variables are not suitable for storing large or complex data like certificates or binary files. Use dedicated secret management tools or configuration services instead. Also, avoid using environment variables for user-generated data or runtime state.

Production Patterns

In production, environment variables are often injected by container orchestration tools like Kubernetes or CI/CD pipelines. Secrets are managed by vaults or cloud secret managers and mapped to environment variables at runtime. Apps use ConfigService with strict validation to ensure safe startup.

Connections

12-Factor App Methodology

Environment variables are a core part of the configuration principle in 12-factor apps.

Understanding environment variables helps grasp how modern apps separate config from code for portability and security.

Operating System Environment

Environment variables in NestJS rely on the OS environment variables mechanism.

Knowing how OS manages environment variables clarifies how apps receive configuration from their host.

Secrets Management

Environment variables often hold secrets, linking them to broader secret management practices.

Recognizing environment variables as part of secret management highlights the importance of secure handling and access control.

Common Pitfalls

#1 Committing .env files with secrets to version control.

Wrong approach:

git add .env
git commit -m "Add env file with passwords"

Correct approach:

Add .env to .gitignore
Use environment-specific secret injection in deployment pipelines

Root cause:

Not understanding that .env files contain sensitive info that should not be shared publicly.

#2 Accessing environment variables directly via process.env everywhere.

Wrong approach:

const dbUrl = process.env.DATABASE_URL;

Correct approach:

constructor(private configService: ConfigService) {}
const dbUrl = this.configService.get('DATABASE_URL');

Root cause:

Ignoring NestJS best practices for configuration management and testability.

#3 Not validating environment variables leading to runtime errors.

Wrong approach:

ConfigModule.forRoot(), no validation schema

Correct approach:

ConfigModule.forRoot({
validationSchema: Joi.object({
DATABASE_URL: Joi.string().required(),
}),
})

Root cause:

Assuming environment variables are always correct and present.

Key Takeaways

Environment variables keep configuration and secrets outside your code, making apps safer and easier to manage.

NestJS uses ConfigModule and ConfigService to load and access environment variables cleanly and safely.

Validating environment variables before app startup prevents bugs and crashes caused by missing or wrong settings.

Use separate .env files for different environments to avoid mixing development and production settings.

Never commit .env files with secrets to version control; use secure secret management and deployment practices.