process.env vs dotenv vs config files — Which Should You Use in Node.js?

// No imports needed — process.env is always available

const port = process.env.PORT || '3000';
const databaseUrl = process.env.DATABASE_URL;
const nodeEnv = process.env.NODE_ENV || 'development';

// Set before running node:
// PORT=8080 DATABASE_URL=postgresql://... node server.js

// Or export in shell:
// export PORT=8080
// node server.js

console.log('Listening on port', port);
console.log('Environment:', nodeEnv);

// All values from process.env are STRINGS — no type coercion
const maxConnections = parseInt(process.env.MAX_CONNECTIONS || '10', 10);
const debugMode = process.env.DEBUG === 'true'; // compare as string

# Install
npm install dotenv

# .env file (never commit this)
PORT=3000
DATABASE_URL=postgresql://postgres:password@localhost:5432/myapp
STRIPE_SECRET_KEY=sk-test-YOUR_KEY
JWT_SECRET=my-super-secret-jwt-signing-key-32-chars

// server.js — load dotenv FIRST, before any other imports
require('dotenv').config();
// Or in ES Modules:
// import 'dotenv/config';

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

// Now process.env has all values from .env merged in
const PORT = process.env.PORT || '3000';
const DATABASE_URL = process.env.DATABASE_URL;

app.listen(parseInt(PORT), () => {
  console.log(`Server running on port ${PORT}`);
});

// dotenv.config() options:
require('dotenv').config({
  path: '.env.local',   // custom file path
  override: true,       // override existing env vars
  debug: true,          // log what dotenv loads
});

npm install dotenv-flow

# File loading order (later files override earlier ones):
# .env           — base, committed to git (non-secret defaults)
# .env.local     — local overrides, NOT committed
# .env.development     — dev-specific, can be committed
# .env.development.local — local dev overrides, NOT committed
# .env.test, .env.production (and their .local variants)

# .env (committed — base defaults, no secrets)
PORT=3000
LOG_LEVEL=info
API_BASE_URL=https://api.myapp.com
FEATURE_NEW_DASHBOARD=false

# .env.development (committed — dev-safe overrides)
LOG_LEVEL=debug
API_BASE_URL=http://localhost:4000
FEATURE_NEW_DASHBOARD=true

# .env.development.local (NOT committed — local secrets)
DATABASE_URL=postgresql://postgres:localpassword@localhost:5432/myapp_dev
STRIPE_SECRET_KEY=sk-test-YOUR_KEY

# .env.production (committed — production non-secret config)
LOG_LEVEL=warn
API_BASE_URL=https://api.myapp.com

// server.js
require('dotenv-flow').config();
// Automatically loads files based on NODE_ENV

// NODE_ENV=development loads:
// .env → .env.local → .env.development → .env.development.local

// NODE_ENV=production loads:
// .env → .env.local → .env.production → .env.production.local

const port = process.env.PORT;
const logLevel = process.env.LOG_LEVEL;
const featureFlag = process.env.FEATURE_NEW_DASHBOARD === 'true';

console.log(`Loaded config for NODE_ENV=${process.env.NODE_ENV}`);

npm install config

# Directory structure:
# config/
#   default.json        — base config (committed)
#   development.json    — dev overrides (committed)
#   production.json     — prod overrides (committed)
#   custom-environment-variables.json  — maps env vars to config keys

// config/default.json
{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "database": {
    "pool": {
      "min": 2,
      "max": 10
    },
    "ssl": false
  },
  "features": {
    "newDashboard": false,
    "betaSignup": false
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

// config/development.json — overrides default.json in development
{
  "server": {
    "port": 3001
  },
  "database": {
    "pool": {
      "min": 1,
      "max": 3
    }
  },
  "features": {
    "newDashboard": true
  },
  "logging": {
    "level": "debug"
  }
}

// config/custom-environment-variables.json
// Maps environment variables to config keys (for secrets)
{
  "database": {
    "url": "DATABASE_URL"
  },
  "stripe": {
    "secretKey": "STRIPE_SECRET_KEY"
  },
  "jwt": {
    "secret": "JWT_SECRET"
  }
}

// server.js — using node-config
const config = require('config');

const port = config.get('server.port');         // number, not string!
const dbUrl = config.get('database.url');       // from DATABASE_URL env var
const poolMax = config.get('database.pool.max');
const featureFlag = config.get('features.newDashboard'); // boolean

// config.get() throws if the key doesn't exist
// config.has() returns false instead of throwing

const stripeKey = config.has('stripe.secretKey')
  ? config.get('stripe.secretKey')
  : null;

// NODE_ENV selects the override file:
// NODE_ENV=development → loads default.json + development.json
// NODE_ENV=production  → loads default.json + production.json

npm install convict
npm install @types/convict  # TypeScript support

// config/index.ts
import convict from 'convict';

const config = convict({
  env: {
    doc: 'The application environment',
    format: ['production', 'development', 'test'],
    default: 'development',
    env: 'NODE_ENV',
  },
  server: {
    port: {
      doc: 'The port to bind the server to',
      format: 'port',        // validates it's a valid port number
      default: 3000,
      env: 'PORT',
      arg: 'port',          // can also be set via --port CLI argument
    },
    host: {
      doc: 'Server hostname',
      format: String,
      default: 'localhost',
      env: 'HOST',
    },
  },
  database: {
    url: {
      doc: 'PostgreSQL connection string',
      format: String,
      default: null,           // null means required — will throw if not set
      env: 'DATABASE_URL',
      sensitive: true,         // redacted in logs
    },
    pool: {
      min: {
        doc: 'Minimum database connections in pool',
        format: 'int',
        default: 2,
        env: 'DB_POOL_MIN',
      },
      max: {
        doc: 'Maximum database connections in pool',
        format: 'int',
        default: 10,
        env: 'DB_POOL_MAX',
      },
    },
  },
  stripe: {
    secretKey: {
      doc: 'Stripe secret API key',
      format: String,
      default: null,
      env: 'STRIPE_SECRET_KEY',
      sensitive: true,
    },
    webhookSecret: {
      doc: 'Stripe webhook signing secret',
      format: String,
      default: null,
      env: 'STRIPE_WEBHOOK_SECRET',
      sensitive: true,
    },
  },
  features: {
    newDashboard: {
      doc: 'Enable the new dashboard UI',
      format: Boolean,
      default: false,
      env: 'FEATURE_NEW_DASHBOARD',
    },
  },
});

// Load environment-specific config file if it exists
const env = config.get('env');
try {
  config.loadFile(`./config/${env}.json`);
} catch {
  // No env-specific file — that's fine
}

// Validate — throws with detailed error message if invalid
config.validate({ allowed: 'strict' });

export default config;

// Usage in your application:
import config from './config';

const port = config.get('server.port');           // type: number (not string!)
const dbUrl = config.get('database.url');         // type: string
const poolMax = config.get('database.pool.max'); // type: number
const featureFlag = config.get('features.newDashboard'); // type: boolean

// config.toString() → prints all config values, REDACTING sensitive ones
console.log(config.toString());
// { server: { port: 3000, host: 'localhost' },
//   database: { url: '[Sensitive]', pool: { min: 2, max: 10 } },
//   stripe: { secretKey: '[Sensitive]', ... } }