Write and read values
Build KV routes that write, read, delete, and return visible JSON responses.
This guide focuses on the route-side calls. It assumes KV is already registered.
Call Pattern
Every route follows the same shape:
- Import
kvfrom@vitehub/kv. - Use a stable string key.
- Await the KV method.
- Return an application response.
server/api/settings.put.ts
import { kv } from '@vitehub/kv'
export default defineEventHandler(async () => {
await kv.set('settings', { enabled: true })
return { ok: true }
})
server/api/settings.get.ts
import { kv } from '@vitehub/kv'
export default defineEventHandler(async () => {
return { settings: await kv.get('settings') }
})
server/api/settings.delete.ts
import { kv } from '@vitehub/kv'
export default defineEventHandler(async () => {
await kv.del('settings')
return { ok: true }
})
Return a Default Value
kv.get() returns null when the key is missing. Normalize that at the route boundary when the client expects a stable shape:
const settings = await kv.get('settings')
return {
settings: settings ?? {
enabled: false,
},
}
Verify the Routes
Write:
curl -X PUT http://localhost:3000/api/settings
Read:
curl http://localhost:3000/api/settings
Expected response:
{
"settings": {
"enabled": true
}
}
Delete:
curl -X DELETE http://localhost:3000/api/settings
Read again:
{
"settings": null
}
Avoid These Mistakes
| Mistake | Fix |
|---|---|
| Building provider-specific clients in every route | Configure kv.driver and use the kv handle. |
Treating null as an object | Check for null or return a default value. |
| Using unscoped keys for feature-owned data | Prefix keys by feature or owner. |