Environment variables and configuration done properly

Why validate configuration at startup?

Because a missing variable discovered at request time produces a confusing runtime error far from its cause.

import { z } from "zod";

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  SESSION_SECRET: z.string().min(32),
  STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
  PORT: z.coerce.number().int().positive().default(3000),
});

// Throws at import time, before the server accepts a single request
export const env = EnvSchema.parse(process.env);

Without this, a missing DATABASE_URL surfaces as 'connect ECONNREFUSED undefined:undefined' during the first request that needs the database — possibly hours after deployment, in a code path unrelated to configuration.

What is the difference between secrets and settings?

Conflating them is why secrets end up in repositories. Once a secret is committed, rewriting history is not enough — it must be rotated, because it may already have been cloned or scraped.

How do client-side variables differ?

• Anything exposed to the browser bundle is public. Not obscure — public, permanently, to anyone who opens devtools.
• Publishable API keys designed for client use are fine. Secret keys never are.
• Framework prefixes such as NEXT_PUBLIC_ exist to make the boundary explicit; respect it.
• Review what is in the client bundle before launch — searching the built output for 'secret' and 'key' takes a minute.
• If a value must stay private, the call using it belongs on the server.

How should configuration differ across environments?

1. 1Same variable names everywhere; only the values change.
2. 2Every environment gets its own secrets — never share production credentials with staging.
3. 3Development uses local or containerised services, not a shared remote database.
4. 4Staging mirrors production configuration as closely as budget allows, so surprises surface there.
5. 5Commit a .env.example listing every variable with placeholder values and a comment for each.
6. 6Validate on every environment, including local, so a new developer's first run tells them what is missing.

What about feature flags?

Environment variables are a poor feature flag mechanism: changing one requires a deploy, and the value is the same for every user. That is fine for a build-time toggle and wrong for anything you want to roll out gradually.

• Build-time toggles (which integrations exist at all): environment variables are appropriate.
• Runtime toggles (enable for 10% of users): a feature flag service or a database-backed flag.
• Kill switches: must be runtime, because needing a deploy to disable a broken feature defeats the purpose.
• Whichever you use, remove flags once the decision is permanent. Stale flags become untested code paths.