Environment Variables

Yama supports environment-specific configuration files for managing different environments.

Loading Order

Environment variables are loaded in priority order (later files override earlier ones):

.env — Base configuration (committed to git)
.env.{environment} — Environment-specific overrides
.env.local — Local overrides (gitignored)

Setting the Environment

The environment is determined by:

--env flag in CLI commands
NODE_ENV environment variable
Defaults to development


# Use development environment (default)
yama dev
 
# Specify environment explicitly
yama dev --env staging
 
# Use NODE_ENV
NODE_ENV=production yama dev

File Structure


your-project/
├── .env                    # Base configuration (committed)
├── .env.development        # Development settings (committed)
├── .env.production         # Production settings (committed)
├── .env.staging            # Staging settings (committed)
└── .env.local              # Local overrides (gitignored)

Example Configuration

`.env` (Base)


# Shared across all environments
PORT=4000
LOG_LEVEL=info

`.env.development`


DATABASE_URL=postgresql://localhost:5432/myapp_dev
JWT_SECRET=dev-secret-key
DEBUG=true

`.env.production`


DATABASE_URL=postgresql://prod-host:5432/myapp_prod
JWT_SECRET=${JWT_SECRET_FROM_VAULT}
DEBUG=false
LOG_LEVEL=warn

`.env.local` (Gitignored)


# Personal overrides
DATABASE_URL=postgresql://localhost:5432/my_local_db
JWT_SECRET=my-personal-secret

Using Variables in yama.yaml

Reference environment variables with ${VAR_NAME} syntax:


database:
  url: ${DATABASE_URL}
 
auth:
  providers:
    - type: jwt
      secret: ${JWT_SECRET}
 
server:
  port: ${PORT:-4000}  # With default value

Default Values

Provide fallback values with :- syntax:


server:
  port: ${PORT:-4000}           # Default to 4000
  host: ${HOST:-0.0.0.0}        # Default to 0.0.0.0
  logLevel: ${LOG_LEVEL:-info}  # Default to info

Required Variables

Document required variables in your README or create .env.example:


# .env.example
# Copy to .env and fill in your values

# Required
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
JWT_SECRET=your-secret-key-here

# Optional
PORT=4000
LOG_LEVEL=info

Commands with Environment

Most commands support the --env flag:


# Development server
yama dev --env development
 
# Schema operations
yama schema:check --env production
yama schema:apply --env staging
 
# Code generation
yama generate --env production

Best Practices

1. Never Commit Secrets

Use .env.local for sensitive values:


# .gitignore
.env.local
.env.*.local

2. Use Environment-Specific Files

Create files for each environment:


.env.development
.env.staging
.env.production

3. Document Required Variables

List all required variables in your README:


## Environment Variables
 
| Variable | Required | Description |
|----------|----------|-------------|
| DATABASE_URL | Yes | PostgreSQL connection string |
| JWT_SECRET | Yes | Secret for JWT signing |
| PORT | No | Server port (default: 4000) |

4. Validate on Startup

Yama validates required environment variables on startup. Missing variables will cause an error.

5. Use Secrets Management in Production

For production, use a secrets manager instead of .env files:

AWS Secrets Manager
HashiCorp Vault
Google Secret Manager
Azure Key Vault