Environment Variables

Environment variables are a type of binding that attach text strings or JSON values to your Worker. They provide a flexible way to manage non-sensitive configuration data that changes between deployments, such as API endpoints, feature flags, and environment-specific settings.

For sensitive information like API keys or passwords, use secrets instead of environment variables.

Add Environment Variables via Wrangler Config

To add environment variables using Wrangler, define text and JSON values via the wrangler.json file.

Basic Configuration

json

Accessing Environment Variables

Environment variables are available through the env parameter in your Agent or MCP Server:

Alternative Access via Node.js process.env

For Node.js compatibility, you can also access environment variables through process.env by enabling the nodejs_compat_populate_process_env compatibility flag in your Wrangler configuration.

Enabling Node.js process.env Support

Add the compatibility flag to your wrangler.json:

json

Runtime Access Only

⚠️ Critical Limitation: process.env variables are only available during runtime execution (inside functions, handlers, and methods). They cannot be accessed at module initialization time.

typescript
typescript

When to Use process.env vs env Parameter

Use env parameter when:

  • Building Cloudflare Workers-specific applications
  • You need reliable access to all bindings (D1, KV, R2, etc.)
  • Working with TypeScript and want full type safety
  • Performance is critical (direct access, no compatibility layer)

Use process.env when:

  • Migrating Node.js applications to Cloudflare Workers
  • Using third-party libraries that expect process.env
  • Maintaining compatibility with existing Node.js codebases
  • Working with tools that automatically populate process.env

Remember: Both approaches access the same underlying environment variables, but process.env requires the compatibility flag and only works at runtime.

Agent Integration

Access environment variables within your Agent class:

typescript

MCP Integration

Access environment variables in your MCP Server:

typescript

Configuring Multiple Environments

Environments in Wrangler let you specify different configurations for the same Worker. Environment variables (vars) are not inherited by environments and must be specified for each environment.

Environment-Specific Configuration

json

Deploy to Specific Environments

Use the --env flag to deploy to specific environments:

bash

Local Development with .dev.vars

For local development, create a .dev.vars file in the root of your project to define variables that will be used when running wrangler dev. This file should be formatted like a dotenv file.

Basic .dev.vars File

bash

Environment-Specific .dev.vars Files

To use different variables for each environment during development, create files named .dev.vars.<environment-name>:

bash
bash

When you run wrangler dev --env staging, the .dev.vars.staging file will be loaded instead of the default .dev.vars file.

Important: Add .dev.vars* files to your .gitignore to prevent accidentally committing local development configuration:

gitignore

Environment Variables vs Secrets

Use Environment Variables For:

  • API endpoints and hostnames
  • Feature flags and configuration toggles
  • Non-sensitive limits and thresholds
  • Environment identifiers
  • Public configuration values

Use Secrets For:

  • API keys and tokens
  • Database passwords
  • Encryption keys
  • Any sensitive data

For sensitive information, use secrets instead of environment variables. Secret values are encrypted and not visible in the Cloudflare dashboard after you define them.

Practical Examples

Feature Flag Configuration

typescript

Environment-Aware Configuration

typescript

JSON Configuration

typescript

Wrangler Configuration Examples

Complete Multi-Environment Setup

json

Best Practices

Naming Conventions

  • Use UPPER_CASE with underscores for environment variable names
  • Group related variables with prefixes (e.g., API_, DB_, FEATURE_)
  • Use descriptive names that clearly indicate the variable's purpose
json

Type Safety

Environment variables, secrets, and service bindings are automatically generated as TypeScript types. In any agent or MCP project, run:

bash

This will automatically update the env.d.ts file with statically generated types for:

  • Environment variables from your wrangler.json configuration
  • Secrets defined in your project
  • Service bindings and other Cloudflare bindings

Example generated types:

typescript

Helper functions for type conversion:

typescript

Validation

Validate environment variables at startup:

typescript

Variable Types and Conversions

  • Strings: Direct access via env.VARIABLE_NAME
  • Numbers: Convert with parseInt() or parseFloat()
  • Booleans: Compare with 'true' or '1' for truthy values
  • JSON: Parse with JSON.parse() for complex objects
  • Arrays: Store as JSON strings and parse with JSON.parse()

Related Resources

For the complete official documentation on Cloudflare Workers environment variables, see the Cloudflare Workers Environment Variables documentation.