Environment Variable Naming Convention: A Practical Guide

Some environment variables look like `DATABASE_URL`; others carry a framework prefix that changes who can read them. A clear environment variable naming convention helps your team tell the difference, keep names consistent, and avoid exposing private values in a browser bundle.

What an Environment Variable Naming Convention Defines

An environment variable is a key-value pair that an app reads from outside its source code. The key names the setting, such as `PORT` or `DATABASE_URL`; the value changes by machine, deployment, or environment.

A naming convention sets the shared rules for those keys. It can define letter case, separators, prefixes, and how much detail a name should include. The goal is simple: a developer should be able to recognize a variable’s purpose without guessing.

For example, `DB_URL` is short but vague. Does it point to a primary database, a test database, or a read replica? `DATABASE_URL` is clearer when there’s one database. If a project has more than one, names such as `DB_PRIMARY_URL` and `DB_REPLICA_URL` can show the difference.

Names also need to work where the app runs. A common portable pattern uses uppercase letters, digits, and underscores, with a letter at the start. Avoid spaces, hyphens, and punctuation. Shells and platforms don’t all parse names the same way, so sticking to this pattern helps prevent avoidable surprises.

A name doesn’t set access control. `STRIPE_SECRET_KEY` may tell a teammate the value is sensitive, but the name itself doesn’t protect it. Store the value in an appropriate secret store, limit who can read it, and keep it out of source control.

SCREAMING_SNAKE_CASE is a widely used shared pattern, and `MYAPP_DATABASE_URL` is an example of an app-specific backend name.

A useful naming policy covers both the shape of a key and the role it plays. Keep one stable key across environments, then supply different values for development, staging, and production.

Why Uppercase Snake Case Is the Common Default

SCREAMING_SNAKE_CASE puts words in uppercase and separates them with underscores. `API_BASE_URL` is easier to scan than `apiBaseUrl` in a shell command or `.env` file. The visual pattern also helps people spot a variable among code written in other naming styles.

It’s a strong default because it’s the most widely used and works with virtually every framework and deployment platform. A shared style cuts down on small mismatches: one person writes `DATABASE_URL`, while another expects `databaseUrl`. The key is still just a name, but consistency makes it easier to wire up correctly.

Prefer clear words over private shorthand. `PAYMENT_API_URL` says more than `PAY_URL`. Use common abbreviations only when everyone on the team knows what they mean. And don’t add words just to make a name sound formal. `PORT` can be enough if there’s only one port setting.

Keep related keys in the same order. For database settings, a team might use `DB_HOST`, `DB_PORT`, and `DB_NAME`. For credentials, `STRIPE_SECRET_KEY` makes the service and value type clear. When a variable has a public and private role, make that distinction plain in the name and documentation.

Keep the same case everywhere

Case behavior differs across systems. Some environments treat `APP_ENV` and `app_env` as separate names. Windows environment variable names are generally case-insensitive, so those forms refer to the same variable there. That mismatch can cause bugs when code moves between a developer’s machine and a Linux-based deployment.

Choose one spelling and use it everywhere. Don’t depend on a system to correct a case mismatch for you. If a variable works on a Windows laptop but fails in a Linux container, compare the spelling in the code with the spelling in the deployment settings.

Set and read the same key in every layer

The syntax for setting a value depends on the shell. In a Bash-style shell, `export APP_ENV=development` sets it for the current session and processes launched from it. In another shell, use its syntax to set `APP_ENV` to `development`. Read a value using the same key: for example, Node.js code can access `process.env.APP_ENV`, while Python can use `os.getenv('APP_ENV')`.

A `.env` file uses a simple `NAME=value` form, such as `APP_ENV=development`. Many frameworks load these files for local work. Keep the key spelling consistent with your code and deployment settings, even if each environment has a different value.

For teams that want to apply the same style across projects, EnvManager’s naming convention rules support organization-wide defaults and project-level overrides. Start by agreeing on the standard, then check existing keys before enforcing it.

When to Use Application and Framework Prefixes

Prefixes add context to a name. An app-specific prefix, such as `MYAPP_`, can help separate your backend’s settings from keys supplied by a hosting platform or another service. It’s most useful when several apps share infrastructure or when a project has a large set of variables.

Don’t prefix every key by habit. If the project is small and names are already distinct, `DATABASE_URL` may be clearer than `MYAPP_DATABASE_URL`. Pick a rule your team can apply consistently, and avoid mixing prefixed and unprefixed names for the same kind of setting.

Framework prefixes are different. Some frameworks use them to mark values that should be included in browser code. That can make the value public, so the prefix is a signal about where a variable can be read, not a way to protect it.

Pattern	Typical use	What to keep in mind
`MYAPP_DATABASE_URL`	App-specific backend setting	Helps avoid name collisions with platform-provided keys.
`VITE_API_BASE_URL`	Client-side build setting in Vite	It’s included in the public bundle. Don’t put a secret in it.
`NEXT_PUBLIC_API_URL`	Client-side value in Next.js	Browser code can access it, so treat the value as public.
`REACT_APP_API_URL`	Client-side build setting in Create React App	It’s embedded in the public bundle. This pattern applies to existing Create React App projects.

Use client-facing prefixes only for values meant to be public, such as an API base URL or a public feature flag. The name can’t make a private credential safe once a build tool has copied its value into JavaScript. A server-side database password belongs in a server-side setting, without a client-exposure prefix.

Build-time and runtime settings also behave differently. A build-time value is read when the app is compiled, so changing it later may require a new build. A server-side runtime value is read by the running process. Keep that distinction in mind when you choose a prefix and set the value in CI/CD.

EnvManager keeps separate values for development, staging, and production. The same key can stay in place while each environment receives its own setting.

Make Names Clear Across Environments Without Exposing Secrets

Use the same key for the same setting across environments. `DATABASE_URL` should mean the database connection in local development, staging, and production. The values change; the name doesn’t. That makes it easier to spot when one deployment is missing a required key.

Keep local `.env` files out of Git. Add them to `.gitignore`, then commit a `.env.example` with the required names and safe placeholder values. That gives teammates a setup checklist without putting working credentials in the repository.

CI/CD pipelines need the same care. Store secrets in the pipeline’s protected secret settings rather than in a checked-in workflow file. Scope values to the environment that needs them, and don’t print secret values in job logs. A misspelled name can still cause a failed build, so check the key in the code, pipeline, and deployment settings.

For Docker Compose, use clear keys in the service’s `environment` or `env_file` configuration. Avoid putting secret values in a Dockerfile, where they can remain in the image. Kubernetes ConfigMaps are for non-sensitive configuration; store sensitive values in a secret manager, with access limited to the workloads and people that need them.

Secret managers affect where values live, not the need for clear names. A team might keep the key `DATABASE_URL` while a secret manager supplies a different value to each deployment. Keep the name stable so the application and deployment setup agree.

Temporary values need a planned end. A shell variable used for one test can disappear when the session ends. A production credential may remain until it’s rotated or revoked. Document who owns a value and when it should be removed, especially when it was created for a short-lived test or deployment.

EnvManager centrally manages encrypted, version-controlled `.env` files and can sync secrets to local machines and CI/CD pipelines. That gives a team one managed place to work with environment values instead of passing them around by hand. Use access controls to limit who can view sensitive values.

Before a release, compare the required variable names across environments and check that no client-side prefix is attached to a secret. If a private value reaches a public bundle or Git history, remove it from future builds and rotate the credential.

FAQ

What is the standard naming convention for environment variables?

Uppercase letters with underscores between words are a common standard. Names such as `DATABASE_URL` and `API_KEY` are easy to spot in shell commands and configuration files. Stick to letters, digits, and underscores for portability, and choose one spelling for each setting across your code, local files, CI/CD, and deployment environment.

Can environment variable names contain hyphens?

It’s safer to avoid hyphens in environment variable names. Shells and tools can treat punctuation differently, which may make a name awkward to set or read. Use underscores instead, as in `API_BASE_URL`. A consistent pattern based on uppercase letters, digits, and underscores is easier to share across languages and deployment systems.

Should environment variables be uppercase?

Uppercase is the usual choice for environment variables, though the exact case rules depend on the operating system. Unix-like systems distinguish names by case, while Windows generally doesn’t. Use uppercase consistently so your app behaves the same when it moves between a local workstation, CI, and a Linux server.

Are `NEXT_PUBLIC_` and `VITE_` variables secret?

No. These prefixes mark values that a build tool can expose to browser code. Treat anything with a client-side prefix as public, even if its name includes words such as `KEY` or `SECRET`. Use these prefixes only for values that are safe for site visitors to see, such as a public API URL.

Conclusion

Use uppercase snake case for a clear default, add prefixes only when they communicate app scope or framework behavior, and keep secrets out of client-side builds and Git. Review your existing keys, write the agreed names in `.env.example`, and use EnvManager if your team needs a shared way to manage and sync `.env` files.