.env vs JSON: feature comparison
| .env / environment variables | JSON config file | |
|---|---|---|
| Structure | flat; nesting by prefix (DB_HOST) | nested objects, arrays |
| Types | strings only, cast in code | string, number, boolean, null |
| Comments | yes (#) | no (JSON5, YAML and TOML have them) |
| Per-environment values | natural: the host sets them | needs one file per environment or overrides |
| Platform support | every host, CI, Docker, Kubernetes | you ship and read the file yourself |
| Secrets | the intended place | easy to commit by accident |
| Changes in production | new deployment or restart | redeploy, or reload if your app watches the file |
When to use which
| Value | Put it in | Why |
|---|---|---|
DATABASE_URL, API keys, signing secrets | .env / host settings | secret and different per environment |
LOG_LEVEL, NODE_ENV, service URLs | .env / host settings | different per environment |
| rate limits, feature flag trees, plan definitions | JSON/YAML in the repo | structured, reviewed in PRs, same everywhere |
| tenant routing tables, i18n bundles | JSON/YAML | large and structured |
| service-account JSON key | one env var (JSON or base64 string) | structured *and* secret |
The hybrid pattern
// config/app.json (committed, no secrets)
// { "rateLimits": { "default": 60, "auth": 10 }, "features": { "darkMode": true } }
import appConfig from "./config/app.json";
import { z } from "zod";
const env = z.object({
DATABASE_URL: z.string().url(),
STRIPE_SECRET_KEY: z.string(),
FEATURE_DARK_MODE: z.enum(["true", "false"]).optional(), // per-env override
}).parse(process.env);
export const config = {
...appConfig,
features: {
...appConfig.features,
darkMode: env.FEATURE_DARK_MODE ? env.FEATURE_DARK_MODE === "true" : appConfig.features.darkMode,
},
databaseUrl: env.DATABASE_URL,
};Structure comes from the file, secrets and per-environment overrides from the environment, and the app imports one merged config object. Validating the environment part is covered in dotenv vs config libraries.
Converting between .env and JSON
- .env → JSON: the ENV to JSON converter parses quotes and comments and can turn
3000andtrueinto real types. - JSON → .env: the JSON to ENV converter flattens
{"db":{"url":…}}intoDB_URL=…and quotes values safely. - YAML: the ENV to YAML converter handles YAML's type pitfalls (
yes,3.10).
Frequently asked questions
Can I put secrets in a JSON config file?
Technically, yes; practically, don't. Config files are meant to be committed and reviewed, so a secret in one will eventually land in git. Keep secrets in environment variables.
How do I store a JSON-shaped secret in .env?
As one value: GOOGLE_CREDENTIALS='{"type":"service_account",…}' in single quotes, or base64-encoded. Parse it once at startup with JSON.parse.
Does a JSON config file break the Twelve-Factor App rules?
Only if it contains values that change between deploys. Twelve-Factor asks that per-deploy config live in the environment; static structure that's identical everywhere can be part of the code.
JSON, YAML or TOML?
Same trade-offs: YAML adds comments and less punctuation (watch its type guessing), TOML is common in Rust and Python tooling, JSON is the strictest. Use whatever your stack already reads.
Can I change a .env value in production without redeploying?
Usually not: most hosts apply variable changes to new deployments or restarted processes only. Values that must change at runtime belong in a feature-flag service or a store your app polls.