Skip to content

Environment Variable Naming Convention

Note

This is an example document that outlines a proposed naming convention for environment variables.

Core Principles

  1. Use UPPERCASE for all variable names
  2. Separate words with underscores
  3. Use prefixes to group related variables
  4. Avoid special characters except underscores
  5. Be descriptive yet concise

General Structure

[PREFIX]_[PROJECT]_[FEATURE]_[SETTING]

  • PREFIX: Environment, component, or service (e.g., APP, DB, API)
  • PROJECT: (Optional) For multiple instances of a service
  • FEATURE: Specific module or functionality
  • SETTING: Actual configuration detail

Common Prefixes

  • APP_: General application settings
  • DB_: Database configurations
  • API_: API-related settings
  • AUTH_: Authentication parameters
  • AWS_: Amazon Web Services
  • SUPABASE_: Supabase projects
  • STRIPE_: Payment processing
  • GCP_: Google Cloud Platform
  • OPENAI_: OpenAI
  • TWILIO_: Twilio
  • SENDGRID_: SendGrid
  • SENTRY_: Sentry
  • DOPPLER_: Doppler

Multiple Project Handling

For services with multiple projects (e.g., Supabase):

  1. Use consistent naming across projects
  2. Include a project identifier after the service prefix
  3. Choose identifiers based on project function

Example:

  • SUPABASE_FLEET_URL
  • SUPABASE_TOOLS_API_KEY
  • SUPABASE_ADS_JWT_SECRET

Best Practices

  1. Avoid sensitive information in variable names
  2. Use TRUE/FALSE for boolean flags
  3. Use numeric suffixes for lists (e.g., ALLOWED_HOSTS_1)
  4. Maintain a .env.example file
  5. Consult service documentation for recommended names
  6. Use environment-specific files (.env.development, .env.production)

Security and Secret Management

  1. Use Doppler for managing all environment variables and secrets
  2. Never commit actual secrets or API keys to version control
  3. Configure Doppler CLI for local development and CI/CD pipelines
  4. Utilize Doppler's environment-specific configurations (e.g., development, staging, production)
  5. Implement Doppler's access controls and audit logging for enhanced security

Debugging

  1. Implement a PRINT_ENV_VARS flag for conditional logging
  2. Add startup checks for required variables

Remember to update documentation when modifying environment variables.