Tired of wrestling with TypeScript config files for dev, staging, and production? A Senior DevOps engineer breaks down three battle-tested methods to manage your environment configuration, from the quick hack to the enterprise-grade solution.

Dear Junior Dev: Stop Fighting Your TypeScript Config and Start Shipping

I still remember the pager going off at 2 AM. It was a Tuesday. A junior dev, eager to please, had pushed a “small fix” to production. The problem? Their `config.ts` file had the staging database connection string hardcoded. We spent the next hour rolling back the change and scrubbing test data that had leaked into the `prod-db-01` cluster. This isn’t just about clean code; it’s about building systems that are resilient to human error. That night taught me a lesson: how you manage your configuration is as critical as the code you write.

The Core of the Problem: Build-Time vs. Runtime

So why is this so frustrating in TypeScript? It comes down to a fundamental conflict. TypeScript is all about build-time safety. It checks your types before the code ever runs. But your configuration—your database URLs, API keys, feature flags—is a runtime concern. The server running your code in staging (`staging-api-01`) needs different values than the one in production. TypeScript can’t know those values when you run `tsc`, and that’s where the pain starts.

The goal is to bridge this gap: get runtime values into a statically typed object your application can trust. Let’s look at three ways to do it, from the “get it done now” hack to the “this will never break” permanent fix.

---

Solution 1: The “It’s 5 PM on a Friday” File Swap

This is the quick and dirty approach. I’ve used it, you’ve probably seen it, and it works in a pinch. The idea is simple: you maintain separate config files for each environment and use your build scripts to swap in the correct one.

You’d have a file structure like this:

/config
  - config.dev.json
  - config.staging.json
  - config.prod.json
/src
  - config.ts
  - ...

Your `config.ts` just imports a generic `config.json` that doesn’t actually exist in that form in your source.

// src/config.ts
import * as config from '../config.json';

export const DATABASE_URL = config.databaseUrl;
export const API_KEY = config.apiKey;

The “magic” happens in your `package.json` scripts, where you copy the correct file over before building.

// package.json
"scripts": {
  "build:dev": "cp ./config/config.dev.json ./config.json && tsc",
  "build:prod": "cp ./config/config.prod.json ./config.json && tsc",
  "start": "node dist/index.js"
}

Warning: This is a hack! It’s brittle because it relies on build scripts running correctly. Most importantly, you risk committing secrets directly to your Git repository, which is a massive security failure. Only use this for non-sensitive data or on a project you need to get running right now.

---

Solution 2: The Professional’s Playbook – Environment Variables & Validation

This is the industry-standard approach and the one we enforce at TechResolve. The principle is simple: separate config from code. Your application should be environment-agnostic. It reads its configuration from the environment it’s running in.

Step 1: Use a .env file for local development.

Create a .env file in your project root. Make sure you add .env to your .gitignore file!

# .env
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
API_KEY="local_dev_key_123"
NODE_ENV="development"

Step 2: Load and Validate at Startup.

Don’t just blindly trust process.env. You’ll lose all your TypeScript benefits. Instead, use a validation library like Zod to parse the environment variables into a strongly-typed, immutable config object when your application starts. If a required variable is missing, the app should crash immediately. Fail fast!

// src/config.ts
import { z } from 'zod';
import dotenv from 'dotenv';

// Load .env file in development
if (process.env.NODE_ENV !== 'production') {
  dotenv.config();
}

const configSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
});

// Parse and validate
const parsedConfig = configSchema.safeParse(process.env);

if (!parsedConfig.success) {
  console.error(
    "❌ Invalid environment variables:",
    parsedConfig.error.flatten().fieldErrors,
  );
  throw new Error("Invalid environment variables.");
}

// Export a read-only, validated config object
export const config = Object.freeze(parsedConfig.data);

Now, anywhere in your app, you can import `config` and get full type-safety and auto-completion:

import { config } from './config';

console.log(`Running in ${config.NODE_ENV} mode.`);
connectToDatabase(config.DATABASE_URL);

Pro Tip: In your CI/CD pipelines for staging and production, you won’t use a .env file. Instead, you’ll inject these variables directly into your server or container environment (e.g., using Kubernetes Secrets, GitHub Actions secrets, or AWS ECS task definitions). This approach is secure, scalable, and follows the Twelve-Factor App methodology.

---

Solution 3: The “Enterprise” Option – External Config Stores

For large-scale systems with many services or extremely sensitive data (think financial or healthcare applications), even environment variables can be a hassle to manage. The “nuclear” option is to externalize your configuration completely.

Services like AWS Systems Manager Parameter Store, AWS Secrets Manager, or HashiCorp Vault are designed for this. Your application doesn’t get the secrets directly. Instead, it gets an IAM role or a token that gives it permission to fetch its configuration from the central store at startup.

Here’s some pseudo-code for what this might look like with AWS Parameter Store:

// src/config-loader.ts (simplified example)
import { SSMClient, GetParametersByPathCommand } from "@aws-sdk/client-ssm";

async function fetchConfigFromAWS() {
  const client = new SSMClient({ region: "us-east-1" });
  const command = new GetParametersByPathCommand({
    Path: "/my-app/prod/",
    WithDecryption: true,
  });

  const response = await client.send(command);
  // ...logic to map parameters to a config object
  // Then validate with Zod just like in Solution 2!
  return mappedConfig;
}

This is the most secure and scalable method, providing a central place to rotate keys, audit access, and manage configuration across your entire fleet. However, it introduces a network dependency at startup and is definite overkill for smaller projects.

Which One Should You Choose?

Here’s my cheat sheet for you:

Approach	Best For	Security	Scalability
1. File Swap	Quick prototypes, non-sensitive data	Poor ☠️	Poor
2. Env Vars + Validation	95% of all projects. The default choice.	Good ✅	Excellent
3. External Store	Large enterprises, high-security needs	Excellent 🛡️	Excellent

My advice? Skip solution #1 unless you absolutely have no other choice. Start with solution #2. It will serve you well from your first side project all the way to a serious production application. It teaches you the right habits and keeps your secrets out of your code. Once you’re running dozens of microservices, you’ll know when it’s time to graduate to #3.

Now, go fix that config. You’ll sleep better, and so will I.

---

🤖 Frequently Asked Questions