Setup
Set up key-value storage with the same provider detection used by NuxtHub.
ViteHub KV automatically configures Nitro Storage, which is built on Unstorage. Register the integration to get the default experience, and add a kv config object only when you need to override the driver.
Getting started
Install the package
Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/kv@main
Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/kv@main
Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/kv@main @upstash/redis
Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/kv@main ioredis
Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/kv@main aws4fetch
Terminal
pnpm add https://pkg.pr.new/nuxt-hub/agent/@vitehub/kv@main
Choose an integration surface
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vitehub/kv/nuxt'],
})
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vitehub/kv/nuxt'],
kv: {
driver: 'cloudflare-kv-binding',
namespaceId: '<kv-namespace-id>',
},
})
Read and write values
server/api/kv.put.ts
import { kv } from '@vitehub/kv'
export default defineEventHandler(async () => {
await kv.set('landing:cta', { clicked: true })
return {
landing: await kv.get('landing:cta'),
}
})
Automatic configuration
ViteHub resolves the KV driver during build in the same order NuxtHub uses:
- explicit
driver - Upstash env
- Redis env
- S3 env
- Cloudflare hosting
- Deno hosting
- local filesystem fallback
On Vercel, ViteHub also detects
KV_REST_API_URL and KV_REST_API_TOKEN for Upstash, and KV_URL for Redis.On Vercel, KV should be backed by Redis or Upstash. If ViteHub still resolves to the filesystem driver, setup emits an explicit error because local KV is not a valid production store there.
Outside hosted environments, ViteHub falls back to the filesystem driver and stores data in
.data/kv.Manual configuration
You can use any Unstorage driver by configuring kv with a driver and its options.
nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vitehub/kv/nuxt'],
kv: {
driver: 'redis',
url: 'redis://localhost:6379',
},
})
Public API
| Method | Use it for |
|---|---|
kv.set(key, value, options?) | Store a value. Pass { ttl } when the driver supports expiration. |
kv.get(key) | Retrieve a value by key. |
kv.has(key) | Check whether a key exists. |
kv.del(key) | Remove a key. |
kv.keys(prefix?) | List all keys, optionally filtered by prefix. |
kv.clear(prefix?) | Remove all keys, optionally scoped to a prefix. |
kv is an Unstorage instance with short aliases. The full Unstorage API (getItem, setItem, removeItem, getKeys) is also available.