Using KV SDK
NuxtHub provides access to the Key-Value storage through an unstorage instance.
Importing the KV storage
NuxtHub provides two ways to import the KV storage:
Recommended: @nuxthub/kv
Use @nuxthub/kv to import the KV storage. This works everywhere, including in Nuxt server routes and external bundlers like Workflow:
import { kv } from '@nuxthub/kv'
Legacy: hub:kv
The virtual module hub:kv is still supported for backwards compatibility (Nuxt only):
import { kv } from 'hub:kv'
kv is auto-imported on the server-side, so you can use it directly without importing.Set an item
Puts an item in the storage.
import { kv } from '@nuxthub/kv'
await kv.set('vue', { year: 2014 })
// using prefixes to organize your KV namespace, useful for the `keys` operation
await kv.set('vue:nuxt', { year: 2016 })
Expiration
By default, items in your KV namespace will never expire. You can delete them manually using the del() method or set a TTL (time to live) in seconds.
The item will be deleted after the TTL has expired. The ttl option maps to Cloudflare's expirationTtl option. Values that have recently been read will continue to return the cached value for up to 60 seconds and may not be immediately deleted for all regions.
import { kv } from '@nuxthub/kv'
await kv.set('vue:nuxt', { year: 2016 }, { ttl: 60 })
Get an item
Retrieves an item from the Key-Value storage.
import { kv } from '@nuxthub/kv'
const vue = await kv.get('vue')
/*
{
year: 2014
}
*/
Has an item
Checks if an item exists in the storage.
import { kv } from '@nuxthub/kv'
const hasAngular = await kv.has('angular') // false
const hasVue = await kv.has('vue') // true
Delete an item
Delete an item with the given key from the storage.
import { kv } from '@nuxthub/kv'
await kv.del('react')
Atomic operations
Redis and Upstash expose two additional operations for single-use values and counters:
import { kv } from '@nuxthub/kv'
if (!kv.getAndDelete || !kv.increment) {
throw new Error('This KV driver does not support atomic operations')
}
const token = await kv.getAndDelete('verification:token')
const attempts = await kv.increment('rate-limit:user', 60)
getAndDelete() returns and removes a value in one operation. increment() returns the post-increment value and applies its TTL only when the counter is created.
These methods are unavailable with Deno KV, Cloudflare KV, S3, and local filesystem storage. Check that the method exists or configure Redis or Upstash before using it.
Clear the KV namespace
Deletes all items from the KV namespace..
import { kv } from '@nuxthub/kv'
await kv.clear()
To delete all items for a specific prefix, you can pass the prefix as an argument. We recommend using prefixes for better organization in your KV namespace.
import { kv } from '@nuxthub/kv'
await kv.clear('react')
List all keys
Retrieves all keys from the KV storage.
import { kv } from '@nuxthub/kv'
const keys = await kv.keys()
/*
[
'react',
'react:gatsby',
'react:next',
'vue',
'vue:nuxt',
'vue:quasar'
]
To get the keys starting with a specific prefix, you can pass the prefix as an argument. We recommend using prefixes for better organization in your KV namespace.
import { kv } from '@nuxthub/kv'
const vueKeys = await kv.keys('vue')
/*
[
'vue:nuxt',
'vue:quasar'
]
*/