Binding reference Bindings

Use KV for fast lookup state without losing a real local loop

KV bindings are first-class in Devflare: author stable names in config, keep env typed, and run real get or put flows locally.

Devflare lets you keep KV intent human-readable in and only resolve opaque namespace ids when build or deploy flows actually need them.

Config key: bindings.kv
Authoring shape: Record<string, string | { name: string } | { id: string }>
Best for: Cache-like lookups, sessions, feature flags, and lightweight request metadata

Author it in the simplest shape that still says what you mean

KV is happiest when you keep the namespace name stable in authored config and let Devflare resolve ids later. That keeps reviews readable and avoids hiding infrastructure intent in random environment variables.

When you truly already know the namespace id, Devflare accepts that too. The important part is that both shapes compile down to the same deploy-facing contract.

KV authoring with stable names or explicit ids

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'kv-worker',

bindings: {

kv: {

CACHE: 'cache-kv',

SESSIONS: { name: 'sessions-kv' },

LEGACY_CACHE: { id: 'kv-namespace-id' }

}

})

When this binding fits best

Reach for KV when reads are by key and you do not need relational queries.
It is a good home for feature flags, lightweight session markers, or cache records that are cheap to recompute.
If you need SQL, batch transactions, or richer query patterns, use D1 instead of forcing KV to act like a database.

Notes worth keeping visible

Rerun after adding or renaming a binding so the generated env contract stays honest.
Preview-scoped names work well for namespace-per-branch flows, but they are still a naming strategy you should review on purpose.
KV is local-friendly, but account-level provisioning behavior still belongs in build, preview, or deploy checks when the lifecycle matters.

The safest authoring instinct

Prefer stable names in source and let Devflare resolve ids later. It keeps config readable without giving up deploy-ready output.

Cloudflare docs vs the Devflare layer

Cloudflare Workers KV docs is the platform reference. This page is the Devflare translation layer: keep readable in source, understand the typed env surface, and know which local, preview, or remote lane actually matches the binding.

Reference

Cloudflare Workers KV docs

Cloudflare Docs

Platform reference for KV namespaces, binding APIs, limits, and Wrangler-facing setup.

Question	Cloudflare docs	This Devflare page
Primary focus	Platform reference for KV namespaces, binding APIs, limits, and Wrangler-facing setup.	How to author , what the runtime surface looks like, and how KV fits a Devflare project.
Testing and runtime lens	Cloudflare’s docs focus on the raw binding API, product semantics, and platform limits for the binding itself.	First-class local runtime and tests. Use the Devflare guidance when you need the honest local harness or the right remote gate instead of only the product API shape.
When to open it	When you need the platform contract, limits, APIs, or account-level product details.	When you are wiring, testing, previewing, or reviewing the binding inside a Devflare app.

Go deeper only if this one-page guide stops being enough

Subpage

KV internals

Internals

See normalization, Wrangler , and the preview or runtime details behind the authored shape.

Subpage

Testing KV

Testing

Start from plus or and only escalate when the binding or deployment model genuinely needs it.

Subpage

KV example

Example

Adapt one small end-to-end path before you hide the binding behind a bigger abstraction.