Back to results for “CI/CD”
Node.js › Environment Variables & Configuration

What is the difference between build-time and runtime configuration for a Node.js application, and why does that distinction matter for container-based deployments?

Advanced

Answer

Build-time configuration is baked into the application artifact when it's built (like a value substituted during a bundler's build step), meaning a different value requires rebuilding the entire artifact -- runtime configuration is read from the environment when the application actually starts, meaning the exact same built artifact can be deployed unchanged to different environments simply by supplying different environment variables at container startup, which is strongly preferred for anything that needs to differ between staging and production, following the twelve-factor methodology.
// Runtime configuration: read when the container starts, same image works everywhere
const apiUrl = process.env.API_URL;

// Build-time (problematic if it needs to differ per environment): baked in during build
// e.g., a frontend bundler replacing process.env.API_URL at build time
// requires a separate build per environment, which breaks 'build once, deploy everywhere'
Real-world example A team discovers their frontend build process was baking the API URL in at build time, requiring a completely separate build for staging versus production; refactoring to read the API URL from a runtime-injected configuration value (fetched from a small config endpoint at page load) lets the exact same built artifact be deployed to every environment.

Common follow-ups: Why does 'build once, deploy everywhere' matter for confidence that what was tested in staging is truly identical to what runs in production?;How do frontend applications, which don't have a Node.js runtime environment available in the browser, work around this same build-time versus runtime tension?