Environment Variable Manager

This skill ensures environment variables are properly added, documented, and configured across all project files and deployment platforms.

Files to Update When Adding Environment Variables

When adding a new environment variable, the following files must be updated in this order:

1.

.env.example

(Required)

Add the variable with a descriptive comment explaining its purpose and expected format.

Format:

# Description of what this variable does
# Options: value1, value2, value3 (if applicable)
# Default: default_value (if applicable)
VARIABLE_NAME=example_value

Example:

# Server port - useful for local development or platform-specific configs
# Default: 3000
PORT=3000

# Node environment - affects Express server optimization
# Options: development, production, test
# Default: (unset)
NODE_ENV=production

2.

server.js

(Required)

Implement the variable usage in the application code.

Pattern:

// Read from environment with fallback default
const variableName = process.env.VARIABLE_NAME || 'default_value';

// For required variables (no default)
const requiredVar = process.env.REQUIRED_VAR;
if (!requiredVar) {
  console.error('ERROR: REQUIRED_VAR environment variable is not set');
  process.exit(1);
}

Examples:

// Optional with default
const port = process.env.PORT || 3000;

// Optional with default
const nodeEnv = process.env.NODE_ENV || 'development';

// Required variable
const apiKey = process.env.API_KEY;
if (!apiKey) {
  console.error('ERROR: API_KEY environment variable must be set');
  process.exit(1);
}

3.

docs/ENVIRONMENT-VARIABLES.md

(Required)

Add comprehensive documentation in the "Currently Supported Variables" section.

Format:

### VARIABLE_NAME

**Purpose**: Brief description of what this variable controls

**Required**: Yes/No

**Default**: `default_value` (or "None - must be set" for required vars)

**Valid Values**:
- `value1`: Description
- `value2`: Description

**Example**:
```bash
VARIABLE_NAME=example_value

Platform Notes:

• AWS Elastic Beanstalk: [specific notes if applicable]
• Google Cloud Run: [specific notes if applicable]
• Docker: [specific notes if applicable]

### 4. `CLAUDE.md` (Required)
Update the "Environment Variables" section to include the new variable in the list.

**Format**:
```markdown
**Currently Supported Variables:**
- `PORT` (optional, defaults to 3000) - Server port. Useful for local development or platform-specific configurations
- `NODE_ENV` (optional) - Node environment: `development`, `production`, or `test`
- `NEW_VARIABLE` (required/optional, defaults to X) - Brief description

5.

docker-compose.yml

(If Applicable)

Add to the environment section if the variable should be set in Docker containers.

Format:

services:
  usa-spending-app:
    environment:
      - NODE_ENV=production
      - PORT=3000
      - NEW_VARIABLE=value

6.

Dockerfile

(If Applicable)

Add ENV directive if the variable needs a build-time or runtime default.

Format:

# For build-time variables
ARG VARIABLE_NAME=default_value

# For runtime variables with defaults
ENV VARIABLE_NAME=default_value

Note: Only add to Dockerfile if a default is truly needed. Prefer runtime configuration via docker-compose.yml or deployment platform.

7. Deployment Documentation (If Platform-Specific)

Update

docs/DEPLOYMENT.md

if the variable requires special handling on specific platforms.

Complete Checklist for Adding Environment Variables

Use this checklist to ensure all steps are completed:

• Add to

  .env.example

  with descriptive comment and example value
• Implement in

  server.js

  with appropriate default or required check
• Document in

  docs/ENVIRONMENT-VARIABLES.md

  with full details
• Update variable list in

  CLAUDE.md

  "Environment Variables" section
• Add to

  docker-compose.yml

  environment section (if applicable)
• Add to

  Dockerfile

  ENV/ARG (if applicable)
• Update

  docs/DEPLOYMENT.md

  with platform-specific instructions (if needed)
• Test locally without

  .env

  file (verify defaults work)
• Test locally with

  .env

  file (verify variable is read correctly)
• Verify

  .env

  is in

  .gitignore

  (should already be there)
• Never commit actual

  .env

  file to repository
• Update

  CHANGELOG.md

  under [Unreleased] > Added section

Security Rules

Sensitive Values

API Keys, Passwords, Secrets, Tokens:

• NEVER hardcode in source code
• NEVER commit to

  .env.example

  with real values (use placeholders)
• MUST use platform-specific secret managers in production:
  • AWS: AWS Secrets Manager or Parameter Store
  • Google Cloud: Secret Manager
  • Heroku: Config Vars (encrypted at rest)
  • Docker: Docker Secrets or external secret management

Non-Sensitive Values

Port numbers, feature flags, public URLs:

• Safe to include in

  .env.example

• Can have defaults in source code

Required vs Optional Variables

Required Variables (no safe default):

const apiKey = process.env.API_KEY;
if (!apiKey) {
  console.error('ERROR: API_KEY is required but not set');
  process.exit(1);
}

Optional Variables (with safe defaults):

const port = process.env.PORT || 3000;
const logLevel = process.env.LOG_LEVEL || 'info';

Platform-Specific Considerations

Google Cloud Run

• PORT: Automatically assigned by Cloud Run (typically 8080). DO NOT hardcode. Application must read from

  process.env.PORT

  .
• Secrets: Use Secret Manager, reference in

  gcloud run deploy

  with

  --set-secrets

AWS Elastic Beanstalk

• PORT: Can be set via environment properties, but application must read from

  process.env.PORT

• Secrets: Use AWS Secrets Manager, reference in

  .ebextensions

  or set via console

AWS ECS/Fargate

• Environment Variables: Set in task definition under

  containerDefinitions[].environment

• Secrets: Use

  secrets

  field in task definition to pull from Secrets Manager or Parameter Store

Heroku

• PORT: Automatically assigned by Heroku. Application must read from

  process.env.PORT

• Config Vars: Set via

  heroku config:set VARIABLE=value

  or dashboard

Docker / Docker Compose

• Environment Variables: Set in

  docker-compose.yml

  under

  environment

  or via

  .env

  file
• Secrets: Use Docker Secrets for swarm mode, or mount secret files as volumes

Common Patterns

Feature Flags

const featureEnabled = process.env.FEATURE_NAME === 'true';
if (featureEnabled) {
  // Feature-specific code
}

API Configuration

const apiBaseUrl = process.env.API_BASE_URL || 'https://api.example.com';
const apiTimeout = parseInt(process.env.API_TIMEOUT || '5000', 10);

Database Configuration

const dbConfig = {
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432', 10),
  database: process.env.DB_NAME || 'myapp',
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD
};

// Validate required fields
if (!dbConfig.user || !dbConfig.password) {
  console.error('ERROR: DB_USER and DB_PASSWORD must be set');
  process.exit(1);
}

Multi-Environment Configuration

const isDevelopment = process.env.NODE_ENV === 'development';
const isProduction = process.env.NODE_ENV === 'production';
const isTest = process.env.NODE_ENV === 'test';

if (isDevelopment) {
  // Development-specific settings
}

Testing Environment Variables

Local Testing Without .env

# Test that defaults work
npm start

# Verify application starts successfully
# Check that default values are used

Local Testing With .env

# Create .env file
cp .env.example .env

# Edit .env with test values
# Run application
npm start

# Verify variables are read correctly

Testing Required Variables

# Test that application fails gracefully when required var is missing
# Remove required variable from .env
npm start

# Should see error message and exit with code 1

Documentation Standards

.env.example Format

# ============================================
# Server Configuration
# ============================================

# Server port
# Default: 3000
PORT=3000

# ============================================
# Application Settings
# ============================================

# Node environment (development, production, test)
# Default: (unset)
NODE_ENV=production

# ============================================
# API Configuration
# ============================================

# External API base URL
# Required: Yes
API_BASE_URL=https://api.example.com

# API timeout in milliseconds
# Default: 5000
API_TIMEOUT=5000

ENVIRONMENT-VARIABLES.md Format

Follow the existing structure in

docs/ENVIRONMENT-VARIABLES.md

:

1. Currently Supported Variables (list with descriptions)
2. Local Development Setup (how to set variables)
3. Platform-Specific Setup (AWS, GCP, Heroku, Docker)
4. Security Best Practices
5. Troubleshooting

Troubleshooting

Variable Not Being Read

1. Check spelling in

   .env

   file matches code exactly
2. Verify

   .env

   file is in project root (same directory as

   server.js

   )
3. Restart server after changing

   .env

   file
4. Check for syntax errors in

   .env

   (no quotes needed, no spaces around

   =

   )
5. Verify

   dotenv

   package is installed if using:

   npm install dotenv

Variable Not Available in Docker

1. Check variable is defined in

   docker-compose.yml

   environment section
2. Rebuild container:

   docker compose up --build

3. Check variable in running container:

   docker exec container_name env | grep VARIABLE

Wrong Default Value Used

1. Verify fallback logic:

   process.env.VAR || 'default'

2. Check for empty string:

   process.env.VAR || 'default'

   (empty string is falsy)
3. For numbers, use:

   parseInt(process.env.VAR || '100', 10)

Current Environment Variables

Reference: See

docs/ENVIRONMENT-VARIABLES.md

for the authoritative list.

Currently Configured:

• PORT

  - Server port (default: 3000)

• NODE_ENV

  - Node environment (default: unset)

Best Practices Summary

1. Always update

   .env.example

   - Never commit actual

   .env

2. Document everything - Update docs/ENVIRONMENT-VARIABLES.md with full details
3. Use descriptive names -

   API_TIMEOUT

   not

   TIMEOUT

   ,

   DB_HOST

   not

   HOST

4. Provide safe defaults - Unless the variable is truly required
5. Validate required variables - Exit with clear error message if missing
6. Never hardcode secrets - Use environment variables and secret managers
7. Test both scenarios - With and without

   .env

   file
8. Keep documentation in sync - Update all files when adding variables
9. Use platform secrets - Don't put sensitive data in environment variables in production
10. Follow naming conventions - UPPER_CASE_WITH_UNDERSCORES

Quick Reference Commands

# Create .env from example
cp .env.example .env

# View current environment variables (local)
printenv | grep -E '(PORT|NODE_ENV)'

# Set variable temporarily (bash/zsh)
export VARIABLE_NAME=value
npm start

# Set variable inline (bash/zsh)
VARIABLE_NAME=value npm start

# Docker Compose with custom env file
docker compose --env-file .env.production up

# Check variable in Docker container
docker exec usa-spending-search env | grep VARIABLE_NAME

# AWS EB set variable
eb setenv VARIABLE_NAME=value

# Heroku set variable
heroku config:set VARIABLE_NAME=value

# GCP Cloud Run set variable
gcloud run services update SERVICE_NAME --set-env-vars="VARIABLE_NAME=value"

Resources

• Project Documentation:

  docs/ENVIRONMENT-VARIABLES.md

• Deployment Guide:

  docs/DEPLOYMENT.md

• Quick Start Guide:

  docs/quick-start-guide.md

• Example Template:

  .env.example