Inject environment variables to the build process via build-time mechanisms: Docker --build-arg, Vite/Next.js .env files, Webpack DefinePlugin, or shell exports at build time. The team that distinguishes build-time vs runtime env vars has correct config (build-time vars are baked into the artifact; runtime vars come from the deployment environment).
Table of contents
- Build-time vs runtime vars
- Docker: —build-arg
- Vite: .env files
- Next.js: NEXT_PUBLIC_ prefix
- Webpack: DefinePlugin
- Jenkins: envinject plugin
- Security: don’t bake secrets
- FAQ
Build-time vs runtime vars
- Build-time: baked into the artifact (image, bundle). E.g., API_URL when building a React app.
- Runtime: supplied at container start or via orchestrator. E.g., DB_PASSWORD at container run.
The team that uses build-time for URLs/endpoints and runtime for secrets has the right split.
Docker: —build-arg
# Dockerfile
ARG API_URL
ENV API_URL=${API_URL}
RUN npm run buildBuild with the arg:
docker build --build-arg API_URL=https://api.example.com -t myapp:1.0 .The team that uses --build-arg has the value baked into the image.
Vite: .env files
Vite reads .env, .env.production, etc. at build time:
# .env.production
VITE_API_URL=https://api.example.com// In code
const apiUrl = import.meta.env.VITE_API_URL;The team that uses .env.production has the value baked into the bundle at build time.
Next.js: NEXT_PUBLIC_ prefix
# .env.production
NEXT_PUBLIC_API_URL=https://api.example.com// Accessible in browser
const apiUrl = process.env.NEXT_PUBLIC_API_URL;The team that uses NEXT_PUBLIC_ prefix has client-side env vars. Other vars are server-side only.
Webpack: DefinePlugin
// webpack.config.js
const webpack = require('webpack');
module.exports = {
plugins: [
new webpack.DefinePlugin({
'process.env.API_URL': JSON.stringify(process.env.API_URL)
})
]
};Build with the env var:
API_URL=https://api.example.com npm run buildThe team that uses DefinePlugin has full control over which env vars are baked in.
Jenkins: envinject plugin
EnvInject captures environment variables for the build:
- Sets them from Jenkins build configuration.
- Injects into the build step.
The team that uses Jenkins for CI/CD has env vars managed in Jenkins UI.
Security: don’t bake secrets
Build-time env vars are PUBLIC in the artifact. If you do docker inspect or look at the bundle, they’re visible.
For secrets, use:
- Runtime env vars: passed at container start, not baked in.
- Secret management: AWS Secrets Manager, HashiCorp Vault, etc.
- Build-time for non-secrets only: API URLs, feature flags.
The team that has build-time secrets in code has them in version control or container history.
FAQ
What’s the difference between build-time and runtime env vars?
Build-time: baked into artifact. Runtime: supplied at container/process start. The team that uses build-time for non-secrets has the right split.
Can I have both build-time and runtime env vars?
Yes - they serve different purposes. Build-time for compile-time constants (API URLs). Runtime for per-deployment config (DB connections).
How do I keep secrets out of my build?
Use runtime env vars for secrets, not build-time. The team that uses Docker secrets or Vault for runtime has secrets out of the build artifact.
Should I commit .env files?
Commit .env.example (placeholders), not .env (real values). The team that uses .env.example has onboarding-friendly config without leaking secrets.
Can I change build-time env vars without rebuilding?
No - they’re baked in. The team that has a bad build-time value has to rebuild the artifact.
If you are sizing the infrastructure for the kind of project this post covers, the RunxBuild hosting calculator is the right place to model the line items. The compute, the memory, the storage, the bandwidth, the database - each one is a separate number, and the team’s mental model for the platform is the sum of those numbers. The RunxBuild dashboard is where the team sees the actual usage in one place.
Useful related references: