KV runtime API

Reference for KV exports, runtime methods, Vite virtual config, config shapes, driver routing, and framework registration.

Use this page when you need exact names, signatures, and option fields. For a guided setup, start with Quickstart.

Imports

Runtime code imports the kv handle from @vitehub/kv:

import { kv } from '@vitehub/kv'

Vite config imports the plugin from @vitehub/kv/vite:

import { hubKv } from '@vitehub/kv/vite'

Runtime Handle

`kv`

kv is a small wrapper around the active Nitro storage mount named kv.

const value = await kv.get('settings')

`KVStorage`

interface KVStorage {
  clear(base?: string, options?: unknown): Promise<void>
  del(key: string, options?: unknown): Promise<void>
  get<T = unknown>(key: string, options?: unknown): Promise<T | null>
  has(key: string, options?: unknown): Promise<boolean>
  keys(base?: string, options?: unknown): Promise<string[]>
  set<T = unknown>(key: string, value: T, options?: unknown): Promise<void>
  store(name: KVStoreName): KVStorage
}

Method	Description
`kv.get(key)`	Read one value. Returns `null` when the key is missing.
`kv.set(key, value, options?)`	Write one value.
`kv.has(key, options?)`	Check whether a key exists.
`kv.del(key, options?)`	Remove one key.
`kv.keys(base?, options?)`	List keys, optionally under a prefix.
`kv.clear(base?, options?)`	Clear the whole store or one prefix.
`kv.store(name)`	Select a named KV store.

Method options are passed to the underlying unstorage driver. Treat them as provider-specific.

Use kv.store(name) when an app has multiple configured stores:

await kv.store('chat').set('thread:1', { status: 'open' })
const state = await kv.store('chat').get('thread:1')

Module Options

`KVModuleOptions`

type KVModuleOptions = KVStoreConfig | KVStoresConfig | false

Set kv: false to disable runtime mounting.

Use stores.default when configuring multiple stores:

kv: {
  stores: {
    default: { driver: 'fs-lite', base: '.data/kv' },
    chat: { driver: 'fs-lite', base: '.data/chat-kv' },
  },
}

`KVDriver`

type KVDriver = 'cloudflare-kv-binding' | 'upstash' | 'fs-lite'

`KVStoreConfig`

type KVStoreConfig =
  | CloudflareKVStoreConfig
  | UpstashKVStoreConfig
  | FsLiteKVStoreConfig

Driver Config Shapes

`CloudflareKVStoreConfig`

{
  driver: 'cloudflare-kv-binding'
  binding?: string
  namespaceId?: string
}

Option	Default	Description
`driver`	required	Selects the Cloudflare KV binding driver.
`binding`	`KV`	Cloudflare binding name.
`namespaceId`	`KV_NAMESPACE_ID` env var	Cloudflare KV namespace ID used to generate Wrangler config.

`UpstashKVStoreConfig`

{
  driver: 'upstash'
  url?: string
  token?: string
}

When credentials come from env vars, ViteHub stores masked placeholders at build time and reads real values at runtime.

Supported env vars:

Value	Env var
REST URL	`KV_REST_API_URL`
REST token	`KV_REST_API_TOKEN`

`FsLiteKVStoreConfig`

{
  driver: 'fs-lite'
  base?: string
}

Option	Default	Description
`driver`	required	Selects the local filesystem driver.
`base`	`.data/kv`	Directory used by the `fs-lite` driver.

Resolution Rules

normalizeKVOptions() resolves the active driver in this order:

kv: false disables KV.
Explicit kv.driver config wins.
Upstash env vars select upstash.
Vercel hosting selects upstash.
Cloudflare hosting selects cloudflare-kv-binding.
Everything else falls back to fs-lite.

Unknown drivers throw:

Unknown `kv.driver`: "...". Expected "cloudflare-kv-binding", "upstash", or "fs-lite".

Non-object config throws:

`kv` must be a plain object.

Vite Plugin API

`hubKv(options?)`

import { hubKv } from '@vitehub/kv/vite'

export default defineConfig({
  plugins: [hubKv({ driver: 'fs-lite' })],
})

The plugin exposes api.getConfig() for tooling and examples:

const plugin = hubKv()
const config = plugin.api.getConfig()

Top-level Vite config kv overrides inline plugin options.

Vite Config Import

Vite code can import the resolved setup config from the stable import path:

import config, { hosting, kv } from '#vitehub/kv/config'

If TypeScript cannot find the generated config surface, add the package's ambient type entry:

tsconfig.json

{
  "compilerOptions": {
    "types": ["@vitehub/kv/virtual"]
  }
}

Nitro Runtime Wiring

The Nitro module:

resolves KV config from nitro.options.kv
writes resolved config to runtimeConfig.kv
mounts the active driver as Nitro storage at kv
aliases @vitehub/kv to the runtime package entry
adds the runtime plugin that remounts lazy Upstash config
adds Cloudflare Wrangler KV namespace config when namespaceId is available

Nuxt Runtime Wiring

The Nuxt module:

reads top-level kv config
installs @vitehub/kv/nitro
forwards kv config to Nitro
does nothing when top-level kv is false