Custom configuration files in NestJS - Deep Dive

Overview - Custom configuration files

What is it?

Custom configuration files in NestJS are user-defined files that store settings and options for your application. They allow you to organize environment-specific or feature-specific data separately from your code. This helps your app adapt to different environments like development, testing, or production without changing the code itself.

Why it matters

Without custom configuration files, you would hardcode settings directly in your app, making it hard to change behavior or deploy in different environments. This can cause bugs, security risks, and slow development. Custom config files let you keep your app flexible, secure, and easier to maintain.

Where it fits

Before learning custom configuration files, you should understand basic NestJS modules and environment variables. After this, you can explore advanced configuration management, validation, and dynamic configuration loading.

Mental Model

Core Idea

Custom configuration files let you separate your app’s settings from code so you can easily change behavior without rewriting code.

Think of it like...

It’s like having a recipe book where the ingredients list is separate from the cooking instructions. You can swap ingredients without changing how you cook.

┌─────────────────────────────┐
│       Application Code       │
│  (uses config values here)   │
└─────────────┬───────────────┘
              │
┌─────────────▼───────────────┐
│    Custom Configuration      │
│  (separate file with values) │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What is a configuration file

Concept: Introduce the idea of storing settings outside code in files.

A configuration file is a simple file that holds settings your app needs, like database addresses or API keys. Instead of writing these directly in your code, you keep them in a separate file. This file can be JSON, YAML, or JavaScript exporting an object.

Result

You understand that configuration files hold app settings separately from code.

Knowing that settings can live outside code helps you keep your app flexible and easier to update.

2

Foundation

Using config files in NestJS basics

Concept: Learn how to load a simple config file in a NestJS app.

In NestJS, you can create a config file like config.ts that exports an object with settings. Then import this file in your modules or services to access those settings. For example, export const config = { port: 3000 }; and import { config } from './config';

Result

Your app can read settings from a separate file instead of hardcoding them.

Separating config from code is easy and improves app organization.

3

Intermediate

Integrating with @nestjs/config module

🤔Before reading on: do you think @nestjs/config automatically reads any file you create, or do you need to tell it which files to load? Commit to your answer.

Concept: Use NestJS’s official config module to manage custom config files with environment support.

NestJS provides @nestjs/config, a module that loads environment variables and custom config files. You register ConfigModule.forRoot({ load: [customConfig] }) where customConfig is a function returning your config object. This lets you organize config in multiple files and access them via ConfigService.

Result

Your app can load custom config files dynamically and access settings via ConfigService.

Using @nestjs/config standardizes config management and supports environment-based configs.

4

Intermediate

Creating environment-specific config files

🤔Before reading on: do you think you should write all environment configs in one file or separate files per environment? Commit to your answer.

Concept: Organize config files by environment to switch settings easily between dev, test, and prod.

Create separate config files like config.dev.ts, config.prod.ts exporting config objects. Use a main config loader that picks which file to load based on NODE_ENV environment variable. This way, your app automatically uses the right settings for the current environment.

Result

Your app adapts config automatically depending on environment without code changes.

Environment-specific config files prevent mistakes and make deployments safer and easier.

5

Advanced

Validating configuration with Joi

🤔Before reading on: do you think config validation is optional or critical for production apps? Commit to your answer.

Concept: Add validation to config values to catch errors early and ensure app stability.

Use Joi schema validation with @nestjs/config by passing validationSchema option to ConfigModule.forRoot(). Define rules for required keys, types, and formats. If config is invalid, the app fails to start, preventing runtime errors.

Result

Your app only runs with valid config, reducing bugs and crashes.

Validating config protects your app from misconfiguration and hard-to-debug errors.

6

Expert

Dynamic and asynchronous config loading

🤔Before reading on: do you think config files can only be static, or can they be generated or fetched at runtime? Commit to your answer.

Concept: Load config dynamically or asynchronously, for example from remote sources or computed values.

NestJS config supports async config loading by passing an async function to load option. This lets you fetch secrets from vaults, call APIs, or compute config values before app starts. It also supports merging multiple config sources.

Result

Your app can use dynamic, secure, and flexible config sources beyond static files.

Dynamic config loading enables advanced use cases like secret management and runtime adaptation.

Under the Hood

NestJS config module reads configuration by executing functions that return config objects. It merges environment variables and custom config files into a single config object stored in a ConfigService singleton. When you inject ConfigService, it provides access to these merged settings. Validation schemas run synchronously during app startup to ensure config correctness.

Why designed this way?

This design separates config loading from usage, supports multiple config sources, and enforces validation early. It avoids hardcoding, supports environment switching, and allows asynchronous fetching of config, which was difficult in older static config approaches.

┌───────────────┐
│ Environment   │
│ Variables     │
└──────┬────────┘
       │
┌──────▼────────┐
│ Custom Config │
│ Files/Funcs   │
└──────┬────────┘
       │
┌──────▼────────┐
│ ConfigModule  │
│ (loads &     │
│ validates)   │
└──────┬────────┘
       │
┌──────▼────────┐
│ ConfigService │
│ (provides    │
│ config to app)│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think custom config files automatically reload when you change them during app runtime? Commit yes or no.

Common Belief: Custom configuration files automatically update the app when changed without restarting.

Reality: Config files are loaded once at app startup; changes require restarting the app to take effect.

Why it matters: Expecting live reload can cause confusion and bugs if config changes are not applied immediately.

Quick: Do you think environment variables and custom config files are the same thing? Commit yes or no.

Common Belief: Environment variables and custom config files are interchangeable and serve the same purpose.

Reality: Environment variables come from the OS environment and are strings, while custom config files are code or structured data you control. They complement each other but are not the same.

Why it matters: Mixing them up can lead to security risks or misconfiguration.

Quick: Do you think you must write all config in one big file for NestJS? Commit yes or no.

Common Belief: All configuration must be in a single file for NestJS to work properly.

Reality: NestJS supports splitting config into multiple files and merging them, improving organization and maintainability.

Why it matters: Believing in one big file leads to messy, hard-to-maintain configs.

Quick: Do you think config validation is optional and only for big projects? Commit yes or no.

Common Belief: Config validation is optional and only needed for very large or complex apps.

Reality: Validation is critical even for small apps to catch errors early and avoid runtime failures.

Why it matters: Skipping validation can cause subtle bugs that are hard to diagnose.

Expert Zone

1

Config functions can depend on environment variables and other config values, enabling computed settings.

2

Merging multiple config sources follows a priority order, which can cause unexpected overrides if not carefully managed.

3

Async config loading can delay app startup, so it should be optimized and used only when necessary.

When NOT to use

Custom configuration files are not ideal when you need real-time config updates without restarting; in such cases, use a centralized config service or feature flags. Also, avoid complex logic inside config files; keep them simple and use services for dynamic behavior.

Production Patterns

In production, teams use environment-specific config files combined with secret management tools. They validate config on startup and use async loaders to fetch secrets securely. ConfigService is injected everywhere to keep code clean and testable.

Connections

Environment Variables

Builds-on

Understanding environment variables helps grasp how custom config files complement and extend environment-based settings.

Dependency Injection

Same pattern

ConfigService uses dependency injection, a core NestJS pattern, to provide config values cleanly across the app.

Software Separation of Concerns

Builds-on

Custom config files embody separation of concerns by isolating configuration from business logic, a key software design principle.

Common Pitfalls

#1 Hardcoding config values inside service files.

Wrong approach:

export class AppService {
private readonly port = 3000;
getPort() { return this.port; }
}

Correct approach:

import { ConfigService } from '@nestjs/config';
export class AppService {
constructor(private configService: ConfigService) {}
getPort() { return this.configService.get('port'); }
}

Root cause:

Not understanding the benefit of separating config from code leads to inflexible and hard-to-maintain apps.

#2 Not validating config, leading to runtime errors.

Wrong approach:

ConfigModule.forRoot({ load: [customConfig] }); // no validationSchema

Correct approach:

import * as Joi from 'joi';
ConfigModule.forRoot({
load: [customConfig],
validationSchema: Joi.object({ port: Joi.number().required() }),
});

Root cause:

Underestimating the importance of config correctness causes bugs that appear only at runtime.

#3 Trying to read config files dynamically at runtime without restart.

Wrong approach:

const config = require('./config');
// expecting changes in config.js to reflect immediately without restart

Correct approach:

Restart the app after changing config files to reload settings properly.

Root cause:

Misunderstanding that config loading happens once at startup.

Key Takeaways

Custom configuration files keep your app’s settings separate from code, making it easier to change behavior without rewriting.

NestJS’s @nestjs/config module helps load, merge, and validate config from multiple sources including custom files and environment variables.

Organizing config by environment ensures your app uses the right settings for development, testing, and production automatically.

Validating config early prevents runtime errors and improves app stability.

Advanced usage includes async and dynamic config loading for secure and flexible applications.