Environment variable management

Environment Variable Management in Engineering Standards

Environment variable management is an indispensable part of front-end engineering. Proper environment variable configuration can enhance team collaboration efficiency, reduce bugs caused by environmental differences, and ensure the security of sensitive information. As project complexity increases, environment variable management requires systematic solutions.

Core Functions of Environment Variables

Environment variables are primarily used to distinguish configuration parameters across different runtime environments (development, testing, production, etc.). Typical scenarios include:

• API base paths
• Third-party SDK keys
• Feature toggles
• Log levels
• Performance monitoring configurations

// Drawbacks of traditional hardcoding
const API_URL = 'https://api.prod.example.com' 

// Environment variable approach
const API_URL = process.env.API_BASE_URL

Hardcoding requires manual code modifications for each deployment, whereas environment variables enable dynamic configuration through external injection.

Common Environment Variable Management Solutions

1. .env File Approach

Modern front-end frameworks widely support .env file management:

# .env.development
VUE_APP_API_URL=https://api.dev.example.com
VUE_APP_DEBUG=true

# .env.production  
VUE_APP_API_URL=https://api.example.com
VUE_APP_DEBUG=false

Toolchains like Create React App and Vue CLI automatically load corresponding files based on NODE_ENV:

// Usage in React
console.log(process.env.REACT_APP_API_URL) 

// Usage in Vue
console.log(process.env.VUE_APP_DEBUG)

2. Build-Time Injection Approach

Build tools like Webpack support environment variable injection:

// webpack.config.js
const webpack = require('webpack')

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.API_KEY': JSON.stringify(process.env.API_KEY)
    })
  ]
}

3. Runtime Loading Approach

For scenarios requiring dynamic configuration, asynchronous loading can be used:

// config.js
export async function loadConfig() {
  const response = await fetch('/config.json')
  window.__APP_CONFIG__ = await response.json()
}

// Usage in components
const apiUrl = window.__APP_CONFIG__.API_URL

Engineering Best Practices

Type-Safe Environment Variables

Use TypeScript to define environment variable types:

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    readonly REACT_APP_API_URL: string
    readonly REACT_APP_ENV: 'development' | 'production'
    readonly REACT_APP_VERSION: string
  }
}

Multi-Environment Management Strategy

A three-tier environment division is recommended:

1. Development environment (development)
2. Staging environment (staging)
3. Production environment (production)

Corresponding directory structure:

config/
  ├── .env.development
  ├── .env.staging
  └── .env.production

Sensitive Information Protection

Avoid exposing sensitive information directly in the front-end:

# Incorrect example
VUE_APP_DB_PASSWORD=123456

# Correct approach
VUE_APP_API_ENDPOINT=/api

Sensitive information should be obtained dynamically through backend APIs or using encryption solutions.

Advanced Application Scenarios

Micro-Frontend Environment Isolation

In micro-frontend architectures, environment variable conflicts must be handled:

// Inject environment variables when the main app loads sub-apps
window.loadMicroApp('sub-app', {
  env: {
    API_PREFIX: '/sub-api'
  }
})

Test Environment Mocking

Implement automated test mocking with environment variables:

// jest.config.js
process.env = {
  ...process.env,
  API_MOCK: 'true'
}

// api.test.js
if (process.env.API_MOCK) {
  jest.mock('../api')
}

Common Issue Solutions

Troubleshooting Environment Variables Not Taking Effect

1. Check if variable naming complies with framework requirements (e.g., Vue requires VUE_APP_ prefix)
2. Confirm .env file placement is correct
3. Restart the development server (some tools require a restart to load new variables)

Cross-Platform Compatibility Handling

Address differences between Windows and Unix environments:

// Unified path handling
const configPath = path.join(
  process.env.HOME || process.env.USERPROFILE,
  '.app_config'
)

Optimization Solutions for Large Projects

For projects with hundreds of environment variables:

1. Split .env files by functional modules
2. Use the env-cmd tool for on-demand loading
3. Establish an environment variable documentation hub

# Load specific files with env-cmd
env-cmd -f .env.feature_x npm start

Toolchain Integration Solutions

Docker Integration Example

FROM node:16

ARG API_BASE_URL
ENV REACT_APP_API_URL=$API_BASE_URL

COPY . .
RUN npm build

Inject variables during build:

docker build --build-arg API_BASE_URL=https://api.example.com .

CI/CD Pipeline Configuration

GitLab CI example:

deploy_prod:
  stage: deploy
  script:
    - echo "VUE_APP_VERSION=$CI_COMMIT_TAG" >> .env
    - npm run build
  only:
    - tags

Browser Compatibility Handling

Support environment variables in older browsers:

// Polyfill for IE11
if (!window.process) {
  window.process = { env: {} }
}

Monitoring and Alert Mechanisms

Establish environment variable health checks:

// Validate required variables at startup
const requiredVars = ['API_URL', 'AUTH_DOMAIN']
requiredVars.forEach(varName => {
  if (!process.env[varName]) {
    console.error(`Missing required env var: ${varName}`)
  }
})

Performance Optimization Directions

1. Avoid frequent access to process.env in business code
2. Inline constants during build
3. Use Tree-shaking to remove unused variables

// Before optimization
function getConfig() {
  return {
    debug: process.env.DEBUG === 'true'
  }
}

// After optimization (transformed via Babel plugin)
function getConfig() {
  return {
    debug: false // Replaced during build
  }
}