Quickstart: KV-Backed Config

Move config into Cloudflare KV when you want the gateway to load its routing definition at runtime.

Move config into Cloudflare KV when you want the gateway to load its routing definition at runtime.

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

wrangler kv:key put --binding=CONFIG api-config.json ./src/api-config.json
wrangler deploy

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

• introduction

• overview

• gateway troubleshooting matrix