Key Value Storage

NuxtHub Key Value Storage automatically configures Nitro Storage, which is built on unstorage.

Getting Started

Enable the key-value storage in your NuxtHub project by adding the kv property to the hub object in your nuxt.config.ts file.

export default defineNuxtConfig({
  hub: {
    kv: true
  }
})

Automatic Configuration

When building the Nuxt app, NuxtHub automatically configures the key-value storage driver on many providers.

pnpm add ioredis

yarn add ioredis

npm install ioredis

bun add ioredis

deno add npm:ioredis

npx nypm add ioredis

{
  "$schema": "node_modules/wrangler/config-schema.json",
  // ...
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "<id>"
    }
  ]
}

Manual Configuration

You can use any unstorage driver by manually configuring the kv mount within your Nitro Storage configuration.

export default defineNuxtConfig({
  nitro: {
    storage: {
      kv: {
        driver: 'redis',
        host: 'localhost',
        port: 6379,
        /* any additional driver options */
      }
    }
  },

  hub: {
    kv: true,
  },
})

Local Development

NuxtHub uses the filesystem during local development. You can modify this behaviour by specifying a different storage driver.

export default defineNuxtConfig({
  nitro: {
    devStorage: {
      kv: {
        driver: 'redis',
        host: 'localhost',
        port: 6379,
      }
    }
  },
})

You can inspect your KV namespace during local development in the Nuxt DevTools.

hubKV()

hubKV() is a server composable that returns an unstorage instance.

Set an item

Puts an item in the storage.

await hubKV().set('vue', { year: 2014 })

// using prefixes to organize your KV namespace, useful for the `keys` operation
await hubKV().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.

await hubKV().set('vue:nuxt', { year: 2016 }, { ttl: 60 })

Get an item

Retrieves an item from the Key-Value storage.

const vue = await hubKV().get('vue')
/*
{
  year: 2014
}
*/

Has an item

Checks if an item exists in the storage.

const hasAngular = await hubKV().has('angular') // false
const hasVue = await hubKV().has('vue') // true

Delete an item

Delete an item with the given key from the storage.

await hubKV().del('react')

Clear the KV namespace

Deletes all items from the KV namespace..

await hubKV().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.

await hubKV().clear('react')

List all keys

Retrieves all keys from the KV storage.

const keys = await hubKV().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.

const vueKeys = await hubKV().keys('vue')
/*
[
  'vue:nuxt',
  'vue:quasar'
]
*/

useStorage()

Server composable that returns an unstorage instance.

As NuxtHub configures and utilizes Nitro Storage under the hood, you can access the unstorage instance directly.

Learn more about useStorage() on the Nitro documentation.

const kv = useStorage('kv')