Environment Configuration

When to use this skill

New Projects: Initial environment setup
Multiple Environments: Separate dev, staging, production
Team Collaboration: Share consistent environments

Instructions

Step 1: .env File Structure

.env.example (template):

Application

NODE_ENV=development PORT=3000 APP_URL=http://localhost:3000

Database

DATABASE_URL=postgresql://user:password@localhost:5432/myapp DATABASE_POOL_MIN=2 DATABASE_POOL_MAX=10

Redis

REDIS_URL=redis://localhost:6379 REDIS_TTL=3600

Authentication

JWT_ACCESS_SECRET=change-me-in-production-min-32-characters JWT_REFRESH_SECRET=change-me-in-production-min-32-characters JWT_ACCESS_EXPIRY=15m JWT_REFRESH_EXPIRY=7d

Email

SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_USER=your-email@gmail.com SMTP_PASSWORD=your-app-password

External APIs

STRIPE_SECRET_KEY=sk_test_xxx STRIPE_PUBLISHABLE_KEY=pk_test_xxx AWS_ACCESS_KEY_ID=AKIAXXXXXXXX AWS_SECRET_ACCESS_KEY=xxxxxxxx AWS_REGION=us-east-1 AWS_S3_BUCKET=myapp-uploads

Monitoring

SENTRY_DSN=https://xxx@sentry.io/xxx LOG_LEVEL=info

Feature Flags

ENABLE_2FA=false ENABLE_ANALYTICS=true

.env.local (per developer):

Developer personal settings (add to .gitignore)

DATABASE_URL=postgresql://localhost:5432/myapp_dev LOG_LEVEL=debug

.env.production:

NODE_ENV=production PORT=8080 APP_URL=https://myapp.com

DATABASE_URL=${DATABASE_URL} # Injected from environment variables REDIS_URL=${REDIS_URL}

JWT_ACCESS_SECRET=${JWT_ACCESS_SECRET} JWT_REFRESH_SECRET=${JWT_REFRESH_SECRET}

LOG_LEVEL=warn ENABLE_2FA=true

Step 2: Type-Safe Environment Variables (TypeScript)

config/env.ts:

import { z } from 'zod'; import dotenv from 'dotenv';

// Load .env file dotenv.config();

// Define schema const envSchema = z.object({ NODE_ENV: z.enum(['development', 'production', 'test']), PORT: z.coerce.number().default(3000),

DATABASE_URL: z.string().url(),

JWT_ACCESS_SECRET: z.string().min(32), JWT_REFRESH_SECRET: z.string().min(32),

SMTP_HOST: z.string(), SMTP_PORT: z.coerce.number(), SMTP_USER: z.string().email(), SMTP_PASSWORD: z.string(),

STRIPE_SECRET_KEY: z.string().startsWith('sk_'),

LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'), });

// Validate and export export const env = envSchema.parse(process.env);

// Usage: // import { env } from './config/env'; // console.log(env.DATABASE_URL); // Type-safe!

Error Handling:

try { const env = envSchema.parse(process.env); } catch (error) { if (error instanceof z.ZodError) { console.error('❌ Invalid environment variables:'); error.errors.forEach((err) => { console.error( - ${err.path.join('.')}: ${err.message}); }); process.exit(1); } }

Step 3: Per-Environment Config Files

config/index.ts:

interface Config { env: string; port: number; database: { url: string; pool: { min: number; max: number }; }; jwt: { accessSecret: string; refreshSecret: string; accessExpiry: string; refreshExpiry: string; }; features: { enable2FA: boolean; enableAnalytics: boolean; }; }

const config: Config = { env: process.env.NODE_ENV || 'development', port: parseInt(process.env.PORT || '3000'),

database: { url: process.env.DATABASE_URL!, pool: { min: parseInt(process.env.DATABASE_POOL_MIN || '2'), max: parseInt(process.env.DATABASE_POOL_MAX || '10'), }, },

jwt: { accessSecret: process.env.JWT_ACCESS_SECRET!, refreshSecret: process.env.JWT_REFRESH_SECRET!, accessExpiry: process.env.JWT_ACCESS_EXPIRY || '15m', refreshExpiry: process.env.JWT_REFRESH_EXPIRY || '7d', },

features: { enable2FA: process.env.ENABLE_2FA === 'true', enableAnalytics: process.env.ENABLE_ANALYTICS !== 'false', }, };

// Validate required fields const requiredEnvVars = [ 'DATABASE_URL', 'JWT_ACCESS_SECRET', 'JWT_REFRESH_SECRET', ];

for (const envVar of requiredEnvVars) { if (!process.env[envVar]) { throw new Error(Missing required environment variable: ${envVar}); } }

export default config;

Step 4: Environment-Specific Configuration Files

config/environments/development.ts:

export default { logging: { level: 'debug', prettyPrint: true, }, cors: { origin: '*', credentials: true, }, rateLimit: { enabled: false, }, };

config/environments/production.ts:

export default { logging: { level: 'warn', prettyPrint: false, }, cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') || [], credentials: true, }, rateLimit: { enabled: true, windowMs: 15 * 60 * 1000, max: 100, }, };

config/index.ts (unified):

import development from './environments/development'; import production from './environments/production';

const env = process.env.NODE_ENV || 'development';

const configs = { development, production, test: development, };

export const environmentConfig = configs[env];

Step 5: Docker Environment Variables

docker-compose.yml:

version: '3.8'

services: app: build: . environment: - NODE_ENV=development - DATABASE_URL=postgresql://postgres:password@db:5432/myapp - REDIS_URL=redis://redis:6379 env_file: - .env.local depends_on: - db - redis

db: image: postgres:15-alpine environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: password POSTGRES_DB: myapp

redis: image: redis:7-alpine

Output format

project/ ├── .env.example # Template (commit) ├── .env # Local (gitignore) ├── .env.local # Per developer (gitignore) ├── .env.production # Production (gitignore or vault) ├── config/ │ ├── index.ts # Main configuration │ ├── env.ts # Environment variable validation │ └── environments/ │ ├── development.ts │ ├── production.ts │ └── test.ts └── .gitignore

.gitignore:

.env .env.local .env.*.local .env.production

Constraints

Required Rules (MUST)

Provide .env.example: List of required environment variables
Validation: Error when required environment variables are missing
.gitignore: Never commit .env files

Prohibited (MUST NOT)

Commit Secrets: Never commit .env files
Hardcoding: Do not hardcode environment-specific settings in code

Best practices

12 Factor App: Manage configuration via environment variables
Type Safety: Runtime validation with Zod
Secrets Management: Use AWS Secrets Manager, Vault

References

dotenv
Zod
12 Factor App - Config

Metadata

Version

Current Version: 1.0.0
Last Updated: 2025-01-01
Compatible Platforms: Claude, ChatGPT, Gemini

environment-setup

Safety Notice

Copy this and send it to your AI assistant to learn