Workers KV in cloudflare.config.ts

Quick configuration

import { bindings, defineConfig } from "cf/config";

export default defineConfig({
  worker: {
    name: "cache-worker",
    compatibilityDate: "2026-09-29",
    entrypoint: "./src/index.ts",
    env: {
      CACHE: bindings.kv({ id: "REPLACE_WITH_NAMESPACE_ID" }),
    },
  },
});

Replace the placeholder with a namespace ID. CACHE is the environment binding; it is not the namespace title. The current typed helper exposes id, not a name option.

Create and identify a namespace

cf kv namespaces create --help

# Creates a remote namespace after authentication
cf kv namespaces create --title notes-cache

Use the returned ID in the configuration. Keep the title for human identification; it cannot replace the ID in this binding example.

Read data in a Worker

export default {
  async fetch(_request: Request, env: { CACHE: KVNamespace }) {
    const message = await env.CACHE.get("welcome");
    return new Response(message ?? "No cached message yet");
  },
};

Generate the Cloudflare runtime types to make KVNamespace available. This example handles an absent key instead of assuming the namespace has already been populated.

Pick the right consistency model

KV is suitable for data that is read frequently and can tolerate delayed visibility after writes. Updates may take 60 seconds or more to reach other locations. A missing-key lookup can be cached as well.

Do not use a successful put followed by an immediate read in another location as a global consistency guarantee. For coordinated state or atomic updates, consider Durable Objects. Choose the storage behavior before choosing its binding helper.

Separate staging and production

import { bindings, defineConfig } from "cf/config";

export default defineConfig(({ mode }) => ({
  worker: {
    name: mode === "production" ? "cache-worker" : "cache-staging",
    compatibilityDate: "2026-09-29",
    entrypoint: "./src/index.ts",
    env: {
      CACHE: bindings.kv({
        id: mode === "production"
          ? "REPLACE_WITH_PRODUCTION_NAMESPACE_ID"
          : "REPLACE_WITH_STAGING_NAMESPACE_ID",
      }),
    },
  },
}));

Replace both identifiers and pass the intended mode explicitly. A different Worker name does not automatically isolate a shared namespace.

Common mistakes

• Passing the namespace title as id.
• Adding a guessed name property that the current helper does not accept.
• Sharing the production namespace with staging unintentionally.
• Assuming local simulation demonstrates globally immediate reads after writes.

Return to cloudflare.config.ts for the overall structure, or use the builder to include KV alongside D1 and R2.