Skip to main content

Multiple Dot Env Files

You can include multiple dot env files by specifying multiple DOT_ENV_FILE parameters. This allows you to compose environment configurations from multiple sources, making it easier to manage complex environment setups.

Overview​

When using multiple dot env files, the files are loaded in order, with later files overriding values from earlier files. The base .env file is always loaded first, followed by any additional files specified via DOT_ENV_FILE parameters.

Using Multiple DOT_ENV_FILE Parameters​

You can specify multiple dot env files using comma-separated values in a single DOT_ENV_FILE parameter:

genx dev -e DOT_ENV_FILE=analytics,redbank

This will load:

  1. client/.env (base file)
  2. client/.env.analytics (first additional file)
  3. client/.env.redbank (second additional file, overrides values from analytics)

Example: Composing Environment Configurations​

In this example, we'll create a configuration that combines analytics features with a specific branding theme.

client/.env​

GENX_ANALYTICS_ENABLED="false"
GENX_ACCENT_COLOR="green"
GENX_API_ENDPOINT="https://api.example.com"

client/.env.analytics​

GENX_ANALYTICS_ENABLED="true"
GENX_ANALYTICS_TRACKING_ID="UA-123456789-1"

client/.env.redbank​

GENX_ACCENT_COLOR="red"
GENX_BRAND_NAME="Red Bank"
GENX_LOGO_URL="/img/redbank-logo.png"

client/globals.d.ts​

declare global {
  // Default generated values
  const API_HOST: string;
  const ENABLE_SSO: boolean;

  // Additional properties
  const GENX_ANALYTICS_ENABLED: string;
  const GENX_ANALYTICS_TRACKING_ID: string;
  const GENX_ACCENT_COLOR: string;
  const GENX_BRAND_NAME: string;
  const GENX_LOGO_URL: string;
  const GENX_API_ENDPOINT: string;
}

export {};

Running with Multiple Files​

To run with both analytics and redbank configurations:

genx dev -e DOT_ENV_FILE=analytics,redbank

This will result in:

  • GENX_ANALYTICS_ENABLED="true" (from .env.analytics)
  • GENX_ANALYTICS_TRACKING_ID="UA-123456789-1" (from .env.analytics)
  • GENX_ACCENT_COLOR="red" (from .env.redbank, overrides default)
  • GENX_BRAND_NAME="Red Bank" (from .env.redbank)
  • GENX_LOGO_URL="/img/redbank-logo.png" (from .env.redbank)
  • GENX_API_ENDPOINT="https://api.example.com" (from base .env)

Example: Environment-Specific Overrides​

You can use multiple files to create environment-specific configurations that build upon each other:

client/.env​

GENX_API_ENDPOINT="https://api.example.com"
GENX_ENABLE_DEBUG="false"

client/.env.staging​

GENX_API_ENDPOINT="https://staging-api.example.com"
GENX_ENABLE_DEBUG="true"

client/.env.staging.override​

GENX_API_ENDPOINT="https://staging-api-override.example.com"
GENX_FEATURE_FLAG_NEW_UI="true"

Running with staging and override:

genx dev -e DOT_ENV_FILE=staging,staging.override

This loads:

  1. .env → GENX_API_ENDPOINT="https://api.example.com", GENX_ENABLE_DEBUG="false"
  2. .env.staging → GENX_API_ENDPOINT="https://staging-api.example.com", GENX_ENABLE_DEBUG="true"
  3. .env.staging.override → GENX_API_ENDPOINT="https://staging-api-override.example.com", GENX_FEATURE_FLAG_NEW_UI="true"

Final values:

  • GENX_API_ENDPOINT="https://staging-api-override.example.com" (from .env.staging.override)
  • GENX_ENABLE_DEBUG="true" (from .env.staging)
  • GENX_FEATURE_FLAG_NEW_UI="true" (from .env.staging.override)

File Loading Order​

Files are loaded in the following order:

  1. Base file: client/.env (always loaded first)
  2. Additional files: Files specified in DOT_ENV_FILE are loaded in the order they appear (left to right)

Values from files loaded later will override values from files loaded earlier. This means:

  • .env values can be overridden by any additional file
  • Files listed earlier in DOT_ENV_FILE can be overridden by files listed later

Best Practices​

  1. Use descriptive file names: Name your env files to clearly indicate their purpose (e.g., .env.analytics, .env.staging, .env.production)

  2. Keep base .env minimal: Put only truly default values in the base .env file

  3. Group related settings: Create separate files for different concerns (analytics, branding, feature flags, etc.)

  4. Document your files: Add comments in your env files explaining what each file is for

  5. Use consistent naming: Follow a consistent naming pattern for your additional env files