[{"data":1,"prerenderedAt":51},["ShallowReactive",2],{"\u002Fcloudflare-config\u002Fkv":3},{"title":4,"description":5,"path":6,"date":7,"updated":8,"verified":7,"category":9,"keywords":10,"officialSources":16,"related":26,"readingTime":30,"html":31,"toc":32},"Workers KV in cloudflare.config.ts","Bind an existing KV namespace by ID with bindings.kv. Use the environment key in Worker code and account for KV’s eventual consistency.","\u002Fcloudflare-config\u002Fkv","2026-09-29","2026-09-30","Configuration",[11,12,13,14,15],"cloudflare.config.ts kv","cloudflare kv config example","cf kv namespace","kv namespace id cloudflare.config.ts","bindings.kv",[17,20,23],{"label":18,"url":19},"Cloudflare configuration types and helpers","https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fworkers-sdk\u002Ftree\u002Fmain\u002Fpackages\u002Fconfig\u002Fsrc",{"label":21,"url":22},"cf CLI source and README","https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fcf\u002Ftree\u002Fmain\u002Fpackages\u002Fcli",{"label":24,"url":25},"How KV works and consistency guarantees","https:\u002F\u002Fdevelopers.cloudflare.com\u002Fkv\u002Fconcepts\u002Fhow-kv-works\u002F",[27,28,29],"\u002Fcloudflare-config","\u002Fcloudflare-config\u002Fdurable-objects","\u002Fcloudflare-config\u002Fd1",2,"\u003Ch2 id=\"quick-configuration\">Quick configuration\u003C\u002Fh2>\n\u003Cdiv class=\"code-block\">\u003Cdiv class=\"code-toolbar\">\u003Cspan>cloudflare.config.ts\u003C\u002Fspan>\u003Cbutton type=\"button\" data-copy-code aria-label=\"Copy code\">Copy\u003C\u002Fbutton>\u003C\u002Fdiv>\u003Cpre>\u003Ccode class=\"hljs language-ts\">\u003Cspan class=\"hljs-keyword\">import\u003C\u002Fspan> { bindings, defineConfig } \u003Cspan class=\"hljs-keyword\">from\u003C\u002Fspan> \u003Cspan class=\"hljs-string\">"cf\u002Fconfig"\u003C\u002Fspan>;\n\n\u003Cspan class=\"hljs-keyword\">export\u003C\u002Fspan> \u003Cspan class=\"hljs-keyword\">default\u003C\u002Fspan> \u003Cspan class=\"hljs-title function_\">defineConfig\u003C\u002Fspan>({\n  \u003Cspan class=\"hljs-attr\">worker\u003C\u002Fspan>: {\n    \u003Cspan class=\"hljs-attr\">name\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">"cache-worker"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-attr\">compatibilityDate\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">"2026-09-29"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-attr\">entrypoint\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">".\u002Fsrc\u002Findex.ts"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-attr\">env\u003C\u002Fspan>: {\n      \u003Cspan class=\"hljs-attr\">CACHE\u003C\u002Fspan>: bindings.\u003Cspan class=\"hljs-title function_\">kv\u003C\u002Fspan>({ \u003Cspan class=\"hljs-attr\">id\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">"REPLACE_WITH_NAMESPACE_ID"\u003C\u002Fspan> }),\n    },\n  },\n});\n\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\u003Cp>Replace the placeholder with a namespace ID. \u003Ccode>CACHE\u003C\u002Fcode> is the environment binding; it is not the namespace title. The current typed helper exposes \u003Ccode>id\u003C\u002Fcode>, not a \u003Ccode>name\u003C\u002Fcode> option.\u003C\u002Fp>\n\u003Ch2 id=\"create-and-identify-a-namespace\">Create and identify a namespace\u003C\u002Fh2>\n\u003Cdiv class=\"code-block\">\u003Cdiv class=\"code-toolbar\">\u003Cspan>Terminal\u003C\u002Fspan>\u003Cbutton type=\"button\" data-copy-code aria-label=\"Copy code\">Copy\u003C\u002Fbutton>\u003C\u002Fdiv>\u003Cpre>\u003Ccode class=\"hljs language-bash\">cf kv namespaces create --\u003Cspan class=\"hljs-built_in\">help\u003C\u002Fspan>\n\n\u003Cspan class=\"hljs-comment\"># Creates a remote namespace after authentication\u003C\u002Fspan>\ncf kv namespaces create --title notes-cache\n\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\u003Cp>Use the returned ID in the configuration. Keep the title for human identification; it cannot replace the ID in this binding example.\u003C\u002Fp>\n\u003Ch2 id=\"read-data-in-a-worker\">Read data in a Worker\u003C\u002Fh2>\n\u003Cdiv class=\"code-block\">\u003Cdiv class=\"code-toolbar\">\u003Cspan>src\u002Findex.ts\u003C\u002Fspan>\u003Cbutton type=\"button\" data-copy-code aria-label=\"Copy code\">Copy\u003C\u002Fbutton>\u003C\u002Fdiv>\u003Cpre>\u003Ccode class=\"hljs language-ts\">\u003Cspan class=\"hljs-keyword\">export\u003C\u002Fspan> \u003Cspan class=\"hljs-keyword\">default\u003C\u002Fspan> {\n  \u003Cspan class=\"hljs-keyword\">async\u003C\u002Fspan> \u003Cspan class=\"hljs-title function_\">fetch\u003C\u002Fspan>(\u003Cspan class=\"hljs-params\">\u003Cspan class=\"hljs-attr\">_request\u003C\u002Fspan>: \u003Cspan class=\"hljs-title class_\">Request\u003C\u002Fspan>, \u003Cspan class=\"hljs-attr\">env\u003C\u002Fspan>: { CACHE: KVNamespace }\u003C\u002Fspan>) {\n    \u003Cspan class=\"hljs-keyword\">const\u003C\u002Fspan> message = \u003Cspan class=\"hljs-keyword\">await\u003C\u002Fspan> env.\u003Cspan class=\"hljs-property\">CACHE\u003C\u002Fspan>.\u003Cspan class=\"hljs-title function_\">get\u003C\u002Fspan>(\u003Cspan class=\"hljs-string\">"welcome"\u003C\u002Fspan>);\n    \u003Cspan class=\"hljs-keyword\">return\u003C\u002Fspan> \u003Cspan class=\"hljs-keyword\">new\u003C\u002Fspan> \u003Cspan class=\"hljs-title class_\">Response\u003C\u002Fspan>(message ?? \u003Cspan class=\"hljs-string\">"No cached message yet"\u003C\u002Fspan>);\n  },\n};\n\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\u003Cp>Generate the Cloudflare runtime types to make \u003Ccode>KVNamespace\u003C\u002Fcode> available. This example handles an absent key instead of assuming the namespace has already been populated.\u003C\u002Fp>\n\u003Ch2 id=\"pick-the-right-consistency-model\">Pick the right consistency model\u003C\u002Fh2>\n\u003Cp>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.\u003C\u002Fp>\n\u003Cp>Do not use a successful \u003Ccode>put\u003C\u002Fcode> followed by an immediate read in another location as a global consistency guarantee. For coordinated state or atomic updates, consider \u003Ca href=\"\u002Fcloudflare-config\u002Fdurable-objects\">Durable Objects\u003C\u002Fa>. Choose the storage behavior before choosing its binding helper.\u003C\u002Fp>\n\u003Ch2 id=\"separate-staging-and-production\">Separate staging and production\u003C\u002Fh2>\n\u003Cdiv class=\"code-block\">\u003Cdiv class=\"code-toolbar\">\u003Cspan>cloudflare.config.ts\u003C\u002Fspan>\u003Cbutton type=\"button\" data-copy-code aria-label=\"Copy code\">Copy\u003C\u002Fbutton>\u003C\u002Fdiv>\u003Cpre>\u003Ccode class=\"hljs language-ts\">\u003Cspan class=\"hljs-keyword\">import\u003C\u002Fspan> { bindings, defineConfig } \u003Cspan class=\"hljs-keyword\">from\u003C\u002Fspan> \u003Cspan class=\"hljs-string\">"cf\u002Fconfig"\u003C\u002Fspan>;\n\n\u003Cspan class=\"hljs-keyword\">export\u003C\u002Fspan> \u003Cspan class=\"hljs-keyword\">default\u003C\u002Fspan> \u003Cspan class=\"hljs-title function_\">defineConfig\u003C\u002Fspan>(\u003Cspan class=\"hljs-function\">(\u003Cspan class=\"hljs-params\">{ mode }\u003C\u002Fspan>) =>\u003C\u002Fspan> ({\n  \u003Cspan class=\"hljs-attr\">worker\u003C\u002Fspan>: {\n    \u003Cspan class=\"hljs-attr\">name\u003C\u002Fspan>: mode === \u003Cspan class=\"hljs-string\">"production"\u003C\u002Fspan> ? \u003Cspan class=\"hljs-string\">"cache-worker"\u003C\u002Fspan> : \u003Cspan class=\"hljs-string\">"cache-staging"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-attr\">compatibilityDate\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">"2026-09-29"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-attr\">entrypoint\u003C\u002Fspan>: \u003Cspan class=\"hljs-string\">".\u002Fsrc\u002Findex.ts"\u003C\u002Fspan>,\n    \u003Cspan class=\"hljs-attr\">env\u003C\u002Fspan>: {\n      \u003Cspan class=\"hljs-attr\">CACHE\u003C\u002Fspan>: bindings.\u003Cspan class=\"hljs-title function_\">kv\u003C\u002Fspan>({\n        \u003Cspan class=\"hljs-attr\">id\u003C\u002Fspan>: mode === \u003Cspan class=\"hljs-string\">"production"\u003C\u002Fspan>\n          ? \u003Cspan class=\"hljs-string\">"REPLACE_WITH_PRODUCTION_NAMESPACE_ID"\u003C\u002Fspan>\n          : \u003Cspan class=\"hljs-string\">"REPLACE_WITH_STAGING_NAMESPACE_ID"\u003C\u002Fspan>,\n      }),\n    },\n  },\n}));\n\u003C\u002Fcode>\u003C\u002Fpre>\u003C\u002Fdiv>\u003Cp>Replace both identifiers and pass the intended mode explicitly. A different Worker name does not automatically isolate a shared namespace.\u003C\u002Fp>\n\u003Ch2 id=\"common-mistakes\">Common mistakes\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>Passing the namespace title as \u003Ccode>id\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>Adding a guessed \u003Ccode>name\u003C\u002Fcode> property that the current helper does not accept.\u003C\u002Fli>\n\u003Cli>Sharing the production namespace with staging unintentionally.\u003C\u002Fli>\n\u003Cli>Assuming local simulation demonstrates globally immediate reads after writes.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Return to \u003Ca href=\"\u002Fcloudflare-config\">cloudflare.config.ts\u003C\u002Fa> for the overall structure, or use the \u003Ca href=\"\u002Fcloudflare-config-builder\">builder\u003C\u002Fa> to include KV alongside D1 and R2.\u003C\u002Fp>\n",[33,36,39,42,45,48],{"id":34,"text":35},"quick-configuration","Quick configuration",{"id":37,"text":38},"create-and-identify-a-namespace","Create and identify a namespace",{"id":40,"text":41},"read-data-in-a-worker","Read data in a Worker",{"id":43,"text":44},"pick-the-right-consistency-model","Pick the right consistency model",{"id":46,"text":47},"separate-staging-and-production","Separate staging and production",{"id":49,"text":50},"common-mistakes","Common mistakes",1790729614466]