ENV Variable Naming Conventions & Best Practices | Ghostable On this page - [Why naming conventions matter](#introduction) - [Recommended conventions](#conventions) - [Common pitfalls](#pitfalls) - [Suggested team standard](#team-standard) - [Good vs. bad examples](#examples) - [How this works with Ghostable](#ghostable) - [Conclusion](#conclusion) - [FAQ](#faq) Environment variables are a shared language across services, platforms, and teams. Clear, consistent naming keeps configs portable, avoids collisions, and prevents painful “it works locally” bugs. This guide gives you pragmatic naming rules you can adopt as a team standard, plus examples and pitfalls to avoid. If you follow the [12-factor “Config” principle](https://12factor.net/config), sane naming is what makes that portability real across languages, shells, and CI/CD runners. --- Why naming conventions matter ----------------------------- - ENV variables are often global and reused across services; sloppy naming causes collisions and misreads. - Consistency improves readability for humans and for automation (CI/CD, scripts, secret stores). - Portability depends on sticking to character sets that shells and containers handle reliably. --- Recommended conventions ----------------------- ### Use UPPERCASE + underscores Stick to SCREAMING\_SNAKE\_CASE: `DB_HOST`, `API_KEY`, `REDIS_URL`. It stands out from code variables and aligns with OS and shell conventions. ### Only letters, digits, and underscore Avoid dots, dashes, and spaces. Portable keys look like `PAYMENTS_WEBHOOK_SECRET`, not `payments.webhook-secret`. ### Meaningful, descriptive names Be explicit: `MAILER_SMTP_HOST` beats `SMTP1`. Add prefixes when multiple services coexist: `ANALYTICS_API_KEY`, `BILLING_DB_HOST`. ### Namespace third-party or shared packages If you publish packages or shared tooling that require env vars, prefix them with a vendor or package name to avoid collisions (`ACME_FEATURE_FLAG_KEY`, `ACME_SEARCH_ENDPOINT`). Document these expectations so host apps know what to set. ### Keep names consistent across environments The key stays the same in dev, staging, and production; only the value changes. This avoids deploy-time mistakes and config drift and pairs well with the [Laravel multi-environment secrets strategy](https://ghostable.dev/learn/laravel-multi-environment-secrets) outlined in our companion guide. ### Start with a letter or underscore Some platforms misbehave with digit-starting names. Keep it simple: `APP_ENV` not `1ST_APP_ENV`. ### Document purpose and format Use `.env.example`, README, or secret-store metadata to describe what each key does, valid formats, and whether it is sensitive. Tools like [Ghostable](https://ghostable.dev) keep that metadata in sync with the actual secrets your team manages. --- Common pitfalls --------------- - Mixing styles (`db_host`, `DATABASE_HOST`, `DbHost`) and causing confusion. - Using dashes, dots, or spaces that break on some shells or make logs ambiguous. - Encoding environment names into keys (`PROD_DB_HOST` vs `DEV_DB_HOST`) instead of keeping one key and varying values. - Skipping documentation, leaving teammates guessing or copying secrets around. --- Suggested team standard ----------------------- 1. All env keys are UPPERCASE. 2. Words separated by underscores only. 3. Allowed characters: A-Z, 0-9, underscore; nothing else. 4. Names are descriptive and prefixed when needed (`SERVICE_DB_HOST`, `PAYMENT_GATEWAY_API_KEY`). 5. Key names are identical across environments; values differ by environment. 6. Do not start names with digits. 7. Document every key: purpose, format, sensitivity, environment usage. 8. Maintain a central reference (.env.example, docs, or secret-store metadata). --- Good vs. bad examples --------------------- Good Bad Notes `APP_ENV` `app-env` Avoid dashes; use underscores. `DATABASE_URL` `database.url` Dots can break in shells and tooling. `PAYMENTS_WEBHOOK_SECRET` `WEBHOOK1` Be descriptive; avoid opaque names. `BILLING_DB_HOST` `PROD_DB_HOST` Prefix by service, not environment. `ANALYTICS_API_KEY` `123APIKEY` Do not start with digits. --- How this works with Ghostable ----------------------------- - **Consistent keys:** A single naming standard keeps secrets aligned across services and environments. - **Collision avoidance:** Prefixing and descriptive names prevent accidental overwrites in shared stores. - **Documentation:** Pair .env.example with Ghostable metadata so teammates know purpose, format, and sensitivity. - **Cross-stack portability:** Uppercase + underscores works for PHP, Node, Python, Ruby, and CI/CD tooling alike. --- Conclusion ---------- Pick a clear naming convention, enforce it, and document it. Uppercase, underscores, descriptive prefixes, and consistent keys across environments will make your configs portable, safer, and easier to automate—whether you are shipping Laravel, Node, or mixed stacks. For a concrete template of how to document keys, see our [Laravel .env.example guide](https://ghostable.dev/learn/laravel-env-example). FAQ Can I use lowercase or camelCase for env keys? Stick with uppercase and underscores. It is the most portable and avoids surprises in shells, Docker, and CI systems. Is it OK to include dots or dashes in env keys? Avoid them. Use only letters, digits, and underscores to prevent parsing issues across platforms. Do key names need to change between dev, staging, and production? Keep key names identical across environments; change only the values. This prevents drift and reduces deploy-time mistakes. How do I prevent collisions across services? Use clear prefixes/namespaces (e.g., BILLING_DB_HOST, ANALYTICS_API_KEY) so different services remain distinct. Where should I document env keys? Use a committed template like .env.example plus README or secret-store metadata describing purpose, format, and sensitivity. Tags [ configuration ](https://ghostable.dev/learn/tag/configuration) [ secrets-management ](https://ghostable.dev/learn/tag/secrets-management) [ naming ](https://ghostable.dev/learn/tag/naming) [ devops ](https://ghostable.dev/learn/tag/devops) On this page - [Why naming conventions matter](#introduction) - [Recommended conventions](#conventions) - [Common pitfalls](#pitfalls) - [Suggested team standard](#team-standard) - [Good vs. bad examples](#examples) - [How this works with Ghostable](#ghostable) - [Conclusion](#conclusion) - [FAQ](#faq) [ Back to Learn ](https://ghostable.dev/learn) Want product news and updates? -------------------------------- Sign up for our newsletter. Email Address Subscribe → Subscribing... We care about your data. Read our [privacy policy](https://ghostable.dev/privacy).