Mapping: Route Variables vs Global Variables

Use route variables for one-off overrides and global variables for cross-route defaults.

Use route variables for one-off overrides and global variables for cross-route defaults.

Last reviewed: 2026-03-06

When to use this

Use this approach when you want a config-first Cloudflare Worker gateway behavior that is already implemented in the repository and covered by tests or canonical examples.

What this does not do

• It does not add unsupported product features such as rate limiting, caching, API keys, analytics, or OpenAPI generation.

• It does not replace upstream application logic that still belongs in your services.

• It does not remove the need to validate environment variables, bindings, and route intent before deploy.

Repo-grounded example

{
  "variables": { "region": "eu-west-1" },
  "paths": [
    {
      "method": "GET",
      "path": "/proxy/{.+}",
      "auth": true,
      "integration": { "type": "http_proxy", "server": "upstream" },
      "mapping": {
        "headers": {
          "x-user-id": "$request.jwt.sub",
          "x-region": "$config.region"
        },
        "query": {
          "source": "$request.query.source"
        }
      },
      "variables": { "api_key": "internal-key" }
    }
  ]
}

This example is grounded in the current implementation shape: JSON config, path-based routing, optional auth, request mapping, and Worker-native integrations.

Troubleshooting

• Confirm the route path and HTTP method match what the worker receives.

• Confirm the config source is the one you expect: local file, KV, or SAG_API_CONFIG_JSON.

• Confirm required bindings and environment variables are present before debugging downstream logic.

• Run the existing tests in the main gateway repo when a config change appears correct but runtime behavior disagrees.

Related docs

• README

• priority variables

• gateway troubleshooting matrix