How to Set Up Environment Variables for Local, Staging, and Production

Overview

If you only need one working definition, use this: environment variables are configuration values supplied from outside your code. They let the same application behave differently depending on where it runs. That usually means changing things like API base URLs, database connections, feature flags, storage buckets, email providers, and secret keys without editing source files for every environment.

A durable environment variable setup should do five things well:

• Separate config from code so you are not editing application logic for each deployment target.
• Keep secrets out of version control so API keys and credentials do not end up in public repos or shared screenshots.
• Make local development fast so new contributors can run the app with a small, documented setup step.
• Support multiple environments cleanly so staging can behave like production without sharing production secrets.
• Fail early when values are missing so configuration errors appear during startup, not after a broken release.

It helps to think of your setup in three layers:

1. Local: values used on your machine during development.
2. Staging: values used in a pre-production environment for testing, QA, and release review.
3. Production: values used by the live app, where stability and secret handling matter most.

One more distinction matters before you begin: public config is not the same as a secret. Frontend projects often expose some variables to browser code at build time, such as a public analytics ID or API origin. Those values may still deserve careful management, but they are not private. Secrets such as database passwords, private API keys, signing secrets, and service account credentials belong only on trusted backend systems or secret stores.

If you are still standardizing your machine setup, it helps to pair this guide with a broader local bootstrapping process such as Local Development Environment Checklist for New Web Projects. The smoother your local environment is, the easier it becomes to keep configuration consistent across the rest of the pipeline.

Checklist by scenario

Use the following scenarios as a practical checklist. You do not need every item for every project, but most teams benefit from following the same structure repeatedly.

1. Local development checklist

Your goal locally is speed, clarity, and safety. Developers should be able to run the app without guessing which values are required.

• Create an example file, such as .env.example, that lists every required variable with placeholder values. Commit this file.
• Keep the real local file uncommitted, such as .env.local or .env, depending on your stack.
• Document which file your framework actually loads. Different frameworks load different filenames and may prioritize them differently.
• Use safe development credentials, not copies of production keys.
• Provide a one-command startup path so the app can validate its variables and fail with a readable message if anything is missing.
• Separate local-only conveniences, such as mock service URLs or debug flags, from variables that must exist in staging and production.

A typical local set might include:

• APP_ENV=development
• PORT=3000
• DATABASE_URL=...
• API_BASE_URL=http://localhost:4000
• JWT_SECRET=local-dev-only-value
• LOG_LEVEL=debug

For backend projects, local secrets still deserve care. They may be low risk, but they should not be copied into chat threads, sample screenshots, or committed accidentally. Adding your env files to .gitignore is basic but essential.

If your project also depends on a specific runtime version, keep that stable alongside your environment setup. That is especially useful in Node projects, where version drift can look like a configuration bug. For that, see Node Version Managers Compared: nvm, fnm, Volta, and asdf.

2. Staging environment checklist

Staging should behave like production where it matters, while remaining safe to test against. The biggest mistake here is treating staging as an afterthought.

• Create a dedicated variable set for staging. Do not point staging at production services unless that is an intentional and documented exception.
• Use separate databases, storage buckets, and third-party app credentials where practical.
• Set staging-specific domains and callback URLs, especially for authentication, payments, and webhooks.
• Keep feature flags explicit so everyone knows whether staging mirrors production or tests upcoming changes.
• Restrict access if staging exposes sensitive internal data or unfinished functionality.
• Test secrets rotation here first when possible, before rotating production equivalents.

Staging is often where URL values multiply: app URL, API URL, asset host, webhook target, OAuth redirect, and email sender settings. Those values should be reviewed together rather than patched one by one. If your app is being deployed to managed hosting, your provider’s environment variable dashboard can help centralize them, but it should not replace written documentation.

When staging deployment is tied to a specific platform, it also helps to understand the platform’s build-time versus runtime behavior. Static and server-rendered deployments can differ significantly. For deployment patterns across modern frontend hosts, see How to Deploy a Static Website to Cloudflare Pages, Netlify, and Vercel and Best Web App Hosting Platforms for Small Projects and Side Hustles.

3. Production environment checklist

Production is where your setup needs the least ambiguity. The safest approach is to make production configuration boring, documented, and hard to change casually.

• Store secrets in the deployment platform’s secret manager or a dedicated secret store, not in source control or ad hoc files on servers.
• Use the minimum required variables. Production sprawl makes rotation and auditing harder.
• Restrict who can view and edit secrets in your hosting or cloud dashboard.
• Rotate high-risk credentials on a schedule or when a contributor leaves, a device is lost, or exposure is suspected.
• Version your configuration process in docs even if the secret values themselves are not versioned.
• Log configuration validation safely without printing secret values.
• Back up recovery steps so your team knows how to restore a missing or overwritten variable during an incident.

Production variables frequently include database URLs, cache endpoints, private API credentials, SMTP credentials, object storage keys, payment webhooks, and signing secrets. Some values may also affect infrastructure behavior, such as region, queue names, or feature flag providers. Those should still be treated as controlled configuration, even when they are not strictly secret.

4. Frontend environment variables checklist

Frontend env vars cause confusion because the word “environment” sounds private even when the values end up in the browser bundle. The rule is simple: if a value is exposed to client-side code, assume users can inspect it.

• Only expose variables meant to be public, such as public app URLs or publishable third-party IDs.
• Use framework-specific prefixes correctly when a tool requires them to expose values to the client.
• Never place private tokens, database credentials, or signing secrets in frontend env vars.
• Know whether values are read at build time or runtime. Many frontend systems bake them into the output during build.
• Rebuild when required after changing public variables, especially on static deployments.

If your frontend talks to APIs with complex query strings or encoded parameters, careful handling of URLs and callback values matters alongside environment setup. A practical companion is URL Encoder and Decoder Guide for Query Strings, Paths, and Form Data.

5. Backend secrets setup checklist

Backend services are where secrets belong. The main goal is to centralize them, validate them, and avoid passing them around informally.

• Load secrets from the environment or a secret manager rather than from hardcoded constants.
• Validate on startup with clear checks for missing, malformed, or obviously wrong values.
• Use separate credentials per environment so local, staging, and production can be isolated.
• Prefer short-lived credentials when your platform supports them, especially for cloud services.
• Mask secrets in logs, error reports, and admin screens.
• Document ownership so someone on the team knows who rotates, updates, and approves changes.

If your backend frequently works with tokens, signatures, or payload inspection, your broader debugging workflow matters too. Related tooling roundups such as Best API Testing Tools for Frontend and Backend Developers and Hash Generator Tools Online: MD5, SHA-256, and HMAC Options Compared can support safer testing without changing your app code.

6. Team documentation checklist

Even a solid env strategy breaks down if only one person understands it.

• Maintain a configuration reference with each variable name, purpose, example value format, and which environments require it.
• Mark variables as secret, internal, or public.
• Explain where each value is managed: local file, CI platform, hosting dashboard, or secret manager.
• Include rotation notes for sensitive credentials.
• Keep onboarding instructions short so new developers can be productive quickly.

If you store broader project configuration in JSON, YAML, or TOML files, keep their role separate from secret handling. This distinction is useful when teams start mixing config files with env-driven values. For that comparison, see JSON vs YAML vs TOML: Which Config Format to Use in Modern Projects.

What to double-check

Before you merge a setup change or trigger a deployment, run through these checks. They catch the most common environment-related issues before they turn into production debugging sessions.

• Variable names are consistent across code, docs, CI, and deployment dashboards.
• Required values are actually present in each environment, not just locally.
• Staging is not accidentally using production secrets.
• Frontend-exposed values are safe to reveal.
• Build-time values and runtime values are not being confused.
• Default fallbacks are intentional. A silent fallback to localhost in production can cause subtle failures.
• Callback URLs, domain values, and DNS-related settings match the real environment. This is especially important after domain changes; see How to Connect a Domain to Your Web App: DNS Records Explained Simply.
• Logs do not print secrets during boot or error handling.
• Rotation steps are documented for any critical secret.
• Example files are current so new team members are not starting from stale variable lists.

A useful pattern is to add a small startup validation layer in your application. It can check for required variables, confirm that URLs are valid, ensure booleans and numbers parse correctly, and stop the app with a readable error if something is wrong. That single step saves time across local development, CI, and deployment.

Common mistakes

Most environment variable problems are not exotic. They come from a few repeated habits.

• Committing real env files to version control. This remains one of the simplest ways to leak credentials.
• Using one shared secret across all environments. That makes testing risky and blast radius larger.
• Assuming frontend env vars are private. If they reach the browser, treat them as public.
• Relying on undocumented local setup. “Ask Alex for the missing key” is not a process.
• Forgetting provider-specific build behavior. Some platforms read variables during build only, others at runtime, and some support both depending on the deployment type.
• Keeping dead variables forever. Old names create confusion and hide which values are still used.
• Skipping validation. Missing config should cause a fast, obvious failure.
• Copying production data paths into staging without realizing it, especially for storage, email, analytics, or payment callbacks.

Another quiet mistake is poor naming. Variables should be explicit enough that someone joining the project can understand them quickly. API_URL may be fine in a simple app, but larger systems benefit from names like PUBLIC_API_BASE_URL, INTERNAL_AUTH_SERVICE_URL, or PAYMENTS_WEBHOOK_SECRET. Clear naming reduces accidental misuse.

When to revisit

Your env setup should not be written once and forgotten. Revisit it whenever the surrounding system changes. A short review at the right time is much cheaper than emergency cleanup after a bad deployment.

Plan to review environment variables in these situations:

• Before seasonal planning cycles, when roadmaps often introduce new services, domains, or release workflows.
• When workflows or tools change, such as moving hosts, adding CI steps, or introducing a secret manager.
• When you add a new third-party integration, especially auth, email, payments, storage, or analytics.
• When domains, subdomains, or DNS records change.
• When a teammate with privileged access leaves or changes roles.
• After an incident involving leaked credentials, failed callbacks, broken builds, or incorrect environment targeting.
• During onboarding improvements, when you notice new developers struggling with setup.

For a practical recurring habit, use this five-step review:

1. List all current variables by environment.
2. Remove anything unused from code, docs, and dashboards.
3. Rotate high-risk secrets if access scope has changed.
4. Update the example file and setup docs.
5. Test local, staging, and production behavior deliberately rather than assuming parity.

The best environment variable strategy is not the most clever one. It is the one your team can understand, audit, and repeat. If you standardize naming, separate secrets from public config, validate values early, and document how each environment is managed, you will avoid a large class of deployment and debugging problems that otherwise keep returning.

Use this article as a checklist before new projects, before platform migrations, and before major releases. Environment variables are infrastructure in miniature: easy to overlook, but foundational when everything else depends on them.