Learning Environment Variables with Watt
What you’ll learn: How to configure your Watt applications using environment variables for different deployment environments, following the twelve-factor app methodology.
By the end of this tutorial, you’ll be able to:
- Configure Watt applications using environment variables
- Use
.envfiles for local development - Set up different configurations for development, staging, and production
- Understand when and why to use environment variables for configuration
Time to complete: 15 minutes
Why Environment Variables Matter
Applications built with Watt follow the twelve-factor app methodology, which recommends storing configuration in environment variables. This approach:
- Separates configuration from code - keeping sensitive data out of your repository
- Enables different environments - development, staging, production with different settings
- Improves security - database passwords and API keys aren’t hardcoded
- Simplifies deployment - same code runs everywhere with different configuration
Step 1: Understanding Variable Replacement
In any Watt configuration file, you can interpolate environment variables using curly braces:
{
"server": {
"port": "{PORT}",
"hostname": "{HOSTNAME}"
},
"runtime": {
"logger": {
"level": "{LOG_LEVEL}"
}
}
}How it works:
- The replacement happens after JSON parsing
- All Watt configuration files support this syntax
- Variables are resolved at startup time
Step 2: Using .env Files for Local Development
Watt has built-in dotenv support, automatically loading environment variables from .env files.
Create a .env file in your project root:
PORT=3042
HOSTNAME=localhost
LOG_LEVEL=info
DATABASE_URL=sqlite://./dev.dbWhere to place .env files:
- Same folder as your Watt configuration file
- Or in the current working directory
- Watt automatically finds and loads them
Step 3: Setting Variables from Command Line
You can override environment variables directly when starting your application:
PORT=4042 LOG_LEVEL=debug npx wattpm devThis is useful for:
- Quick testing with different values
- CI/CD pipeline overrides
- One-off debugging sessions
Step 4: Environment-Specific Configuration
You can create different .env files for different environments and specify which one to use with the --env flag:
PORT=3042
LOG_LEVEL=debug
DATABASE_URL=sqlite://./dev.dbPORT=3000
LOG_LEVEL=warn
DATABASE_URL=postgresql://user:pass@prod-db:5432/myappLoad specific environment files:
# Development
npx wattpm dev --env .env.development
# Production
npx wattpm start --env .env.productionNote: By default, Watt only loads .env files automatically. To use environment-specific files like .env.development or .env.production, you must explicitly specify them using the --env flag.
Step 5: Common Configuration Patterns
Database Configuration
{
"db": {
"connectionString": "{DATABASE_URL}",
"pool": {
"max": "{DB_POOL_SIZE}"
}
}
}DATABASE_URL=postgresql://localhost:5432/myapp
DB_POOL_SIZE=10Application Configuration
{
"server": {
"port": "{PORT}",
"hostname": "{HOSTNAME}"
},
"cors": {
"origin": "{CORS_ORIGIN}"
}
}PORT=3042
HOSTNAME=0.0.0.0
CORS_ORIGIN=http://localhost:3000Success Criteria
You’ve successfully learned environment variables when you can:
Replace hardcoded values in configuration files with environment variables
Create and use .env files for local development
Set up different configurations for different environments
Override variables from the command line
Understand why this approach improves security and deployment flexibility
What’s Next?
Now that you understand environment variables, you might want to:
- Learn database configuration - Apply environment variables to database setup
- Explore deployment guides - Use environment variables in production
- Build a full application - Practice with a complete example
Troubleshooting
Variable not being replaced?
- Check curly brace syntax:
{VARIABLE_NAME}not${VARIABLE_NAME} - Ensure the variable is set:
echo $VARIABLE_NAME - Verify
.envfile location (same folder as config file)
Environment-specific file not loading?
- Make sure you’re using the
--envflag:wattpm start --env .env.production - Check that the file path is correct (relative or absolute)
- Verify the file exists:
ls -la .env.production - Remember: command line variables override
.envfiles