Environment Variables and Configuration in Cloudflare Workers

Previously in this course, we covered Managing Secrets Securely, where we learned how to inject sensitive keys into our environment without hardcoding them. In this lesson, we add a layer of operational maturity: managing non-sensitive application settings across different deployment environments using wrangler.toml.

Understanding Configuration vs. Secrets

In software engineering, we often conflate secrets (API keys, database passwords) with configuration (feature flags, API base URLs, log levels). While Managing Secrets Securely handles the former, configuration needs to be visible, version-controlled, and environment-aware.

Using environment variables for configuration allows you to promote the same code artifact across development, staging, and production environments without changing a single line of application logic. This is a core tenet of DevOps, similar to patterns seen in Managing Environment Variables: A Docker Configuration Guide or Using Environment Variables in Lambda: A Configuration Guide.

Defining Environments in wrangler.toml

The wrangler.toml file is the heart of your Worker’s configuration. By default, it applies to your main deployment. However, you can define specific environment blocks to override settings based on where the code is running.

Here is how you structure your wrangler.toml to support a dev and prod environment:

TOML
name = "my-project"
main = "src/index.js"

# Global settings (default)
[vars]
API_TIMEOUT = 5000
DEBUG_MODE = false

[env.production]
vars = { API_TIMEOUT = 1000, DEBUG_MODE = false }

[env.development]
vars = { API_TIMEOUT = 10000, DEBUG_MODE = true }

When you run npx wrangler deploy, Cloudflare uses the top-level configuration. When you run npx wrangler deploy --env production, it merges the env.production block with the root configuration, overriding specific values.

Worked Example: Toggling Features

Let’s apply this to our running project. Suppose we want to toggle a "Maintenance Mode" or change the API source based on our environment.

1. Modify wrangler.toml: Add an ENVIRONMENT variable to your configuration to let your code know where it is running.

TOML
[vars]
ENVIRONMENT = "staging"

[env.production]
vars = { ENVIRONMENT = "production" }

1. Accessing Variables in your Worker: Cloudflare injects these variables into the env object passed to your handler.

JAVASCRIPT
export default {
  async fetch(request, env, ctx) {
    if (env.ENVIRONMENT === "production") {
      // Production-specific logic
      console.log("Running in production mode");
    } else {
      // Development or staging logic
      console.log("Running in debug mode");
    }
    return new Response(CE9178">`Current environment: ${env.ENVIRONMENT}`);
  }
};

Hands-on Exercise

1. Open your project's wrangler.toml.
2. Add a [env.dev] block and a [env.prod] block.
3. Define a variable called APP_VERSION in both blocks with different values (e.g., "1.0.0-beta" for dev, "1.0.0" for prod).
4. Update your index.js to return the APP_VERSION in the response body.
5. Deploy to dev using wrangler deploy --env dev and observe the output when you hit your URL.

Common Pitfalls

• Environment Name Collisions: Ensure your environment names in wrangler.toml do not conflict with reserved Cloudflare terms. Stick to simple names like dev, staging, and prod.
• Deployment Confusion: Forgetting to specify --env <name> during deployment will default to the top-level configuration, which might lead to deploying production-grade code with development settings.
• Variable Shadowing: If you define a variable in the root [vars] block and again in an [env] block, the [env] block wins. Keep your root settings for global defaults and your environment blocks for specific overrides.

FAQ

Q: Can I use environment variables to change D1 database bindings? A: Yes, you can define different D1 database bindings inside environment blocks, allowing you to point your app to a dev_db during testing and prod_db during production.

Q: Are environment variables secure? A: Environment variables defined in wrangler.toml are visible to anyone with access to the source code repository. Never put sensitive credentials here; use wrangler secret as discussed in Managing Secrets Securely.

Recap

Configuration management is the bridge between code and operational reality. By using wrangler.toml to define distinct environments, you gain the ability to toggle debug features, point to different databases, and control runtime behavior without modifying your core application logic. This approach ensures your deployment remains predictable and reproducible.

Up next: Project Milestone: Securing the Full Stack — we will use these configuration techniques to enforce authentication and security rules across our entire production-ready application.