Skip to content
Select documentation version
Navigation
On this page

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 .env files 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.db

Where 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 dev

This 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.db
PORT=3000
LOG_LEVEL=warn
DATABASE_URL=postgresql://user:pass@prod-db:5432/myapp

Load specific environment files:

# Development
npx wattpm dev --env .env.development

# Production
npx wattpm start --env .env.production

Note: 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=10

Application Configuration

{
  "server": {
    "port": "{PORT}",
    "hostname": "{HOSTNAME}"
  },
  "cors": {
    "origin": "{CORS_ORIGIN}"
  }
}
PORT=3042
HOSTNAME=0.0.0.0
CORS_ORIGIN=http://localhost:3000

Success 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:

Troubleshooting

Variable not being replaced?

  • Check curly brace syntax: {VARIABLE_NAME} not ${VARIABLE_NAME}
  • Ensure the variable is set: echo $VARIABLE_NAME
  • Verify .env file location (same folder as config file)

Environment-specific file not loading?

  • Make sure you’re using the --env flag: 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 .env files
Reading time
3 min read
View as
Markdown
Contribute
Edit this page