compareBy Aliniyaz Mamat · updated

.env vs JSON config: when to use which

.env vs JSON config: use a .env file (and real environment variables in production) for secrets and values that change per environment; use JSON, YAML or TOML for structured, non-secret configuration such as feature-flag trees, routing tables or limits. Most production apps combine both.

Key takeaways

  • ✓.env is flat KEY=value text, read by every platform and loader; JSON adds nesting, arrays and types.
  • ✓Secrets belong in environment variables, never in a committed JSON file.
  • ✓Values that differ between dev, staging and production → environment; values that are the same everywhere → structured config file.
  • ✓A secret that is itself JSON (e.g. a service-account key) can live in one variable as a JSON or base64 string.
  • ✓Converting is mechanical: ENV to JSON and JSON to ENV do it in the browser.

.env vs JSON: feature comparison

.env / environment variablesJSON config file
Structureflat; nesting by prefix (DB_HOST)nested objects, arrays
Typesstrings only, cast in codestring, number, boolean, null
Commentsyes (#)no (JSON5, YAML and TOML have them)
Per-environment valuesnatural: the host sets themneeds one file per environment or overrides
Platform supportevery host, CI, Docker, Kubernetesyou ship and read the file yourself
Secretsthe intended placeeasy to commit by accident
Changes in productionnew deployment or restartredeploy, or reload if your app watches the file

When to use which

ValuePut it inWhy
DATABASE_URL, API keys, signing secrets.env / host settingssecret and different per environment
LOG_LEVEL, NODE_ENV, service URLs.env / host settingsdifferent per environment
rate limits, feature flag trees, plan definitionsJSON/YAML in the repostructured, reviewed in PRs, same everywhere
tenant routing tables, i18n bundlesJSON/YAMLlarge and structured
service-account JSON keyone 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

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.

Related tools

Continue reading