Binding reference Bindings

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

Workers KV is a global key-value store for low-latency reads and lightweight shared data.

Author stable KV 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
Authoring shape
Best for: Cache-like lookups, sessions, feature flags, and lightweight request metadata

Add the binding to config

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' },

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

}

})

Use the binding from application code

After Devflare generates the worker env, import from and keep the first KV path close to the route, handler, or service method that needs it.

Keep this first path small enough that the config, env binding, and user-visible behavior are easy to review together.

A tiny fetch handler that uses KV

import { env } from 'devflare/runtime'

export async function fetch(request: Request): Promise<Response> {

const url = new URL(request.url)

if (url.pathname === '/write') {

await env.CACHE.put('hello', 'from-kv')

return new Response('stored')

}

return new Response((await env.CACHE.get('hello')) ?? 'missing')

}

Local and Remote Support

Devflare can run useful KV application behavior locally for ordinary development and tests. Cloudflare still owns production limits, quotas, billing, and deployed account behavior.

Local runtime and tests. Start locally with plus or ; that lane should cover the normal KV application flow without requiring a Cloudflare connection.

Use Cloudflare when the assertion depends on deployed limits, account state, lifecycle behavior, billing, or other production-only KV details.

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.

Testing path

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 worth reviewing.
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.

Open the next page when you need it

Subpage

KV internals

Internals

Check emitted Wrangler , preview behavior, and Cloudflare-specific details.

Subpage

Testing KV

Testing

Pick the plus or path first, then move to remote checks only when the test needs them.

Subpage

KV example

Example

Copy a fuller application path when the quick example is too small.