principletypescriptTip

Twelve-factor app: the canonical checklist for cloud-native microservices

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

twelve-factor12-factorcloud-nativeconfigenvironment variablesstatelesshorizontal scalingherokudisposability

Problem

A microservice works locally but behaves differently in staging. Config is hardcoded, dependencies are bundled, and logs go to files. The service cannot scale horizontally without manual intervention.

Solution

Apply the Twelve-Factor methodology. Critical factors for microservices: store config in environment variables (factor III), treat backing services as attached resources (factor IV), export logs as event streams to stdout (factor XI), and run stateless processes (factor VI).

// Factor III: config from environment
const config = {
  dbUrl: process.env.DATABASE_URL!,
  redisUrl: process.env.REDIS_URL!,
  port: parseInt(process.env.PORT ?? '3000'),
};

// Factor XI: log to stdout
console.log(JSON.stringify({ level: 'info', message: 'Server started', port: config.port }));

Why

The twelve factors encode the hard-won lessons of running services at scale on platforms like Heroku, Kubernetes, and Fly. They exist to maximise portability and minimise divergence between environments.

Gotchas

Secrets should not be in environment variables in plain text — use a secrets manager (Vault, AWS Secrets Manager) and inject at runtime
Factor X (dev/prod parity) is the most violated — use Docker Compose to replicate the prod stack locally
Factor IX (disposability) requires fast startup and graceful shutdown — handle SIGTERM correctly
Twelve-factor is prescriptive about what, not how — adapt to your platform

Context

Designing new microservices or auditing existing ones for cloud-native readiness

Revisions (0)

No revisions yet.