KV Storage

Nitro has built-in integration with unjs/unstorage to provide a runtime agnostic persistent layer.

Usage

To use the storage layer, you can use the useStorage() and call getItem(key) to retrieve an item and setItem(key, value) to set an item.

// Default storage is in memory
await useStorage().setItem('test:foo', { hello: 'world' })
await useStorage().getItem('test:foo')

// You can also specify the base in useStorage(base)
await useStorage('test').setItem('foo', { hello: 'world' })

// You can use data storage to write data to default .data/kv directory
const dataStorage = useStorage('data').setItem('test', 'works')
await useStorage().getItem('data:test') // Value persists

// You can use generics to define types
await useStorage<{ hello: string }>('test').getItem('foo')
await useStorage('test').getItem<{ hello: string }>('foo')

Configuration

You can mount one or multiple custom storage drivers using the storage config. The key is the mount point name, and the value is the driver name and configuration.

export default defineNitroConfig({
  storage: {
    redis: {
      driver: 'redis',
      /* redis connector options */
    },
    db: {
      driver: 'fs',
      base: './data/db'
    }
  }
})

Runtime configuration

In scenarios where the mount point configuration is not known until runtime, Nitro can dynamically add mount points during startup using plugins.

import redisDriver from 'unstorage/drivers/redis'

export default defineNitroPlugin(() => {
  const storage = useStorage()

  // Dynamically pass in credentials from runtime configuration, or other sources
  const driver = redisDriver({
      base: 'redis',
      host: useRuntimeConfig().redis.host,
      port: useRuntimeConfig().redis.port,
      /* other redis connector options */
    })

  // Mount driver
  storage.mount('redis', driver)
})

Development-only mount points

By default, Nitro will mount the project directory and some other dirs using the filesystem driver in development time.

// Access to project root dir
const rootStorage = useStorage('root')

// Access to project src dir (same as root by default)
const srcStorage = useStorage('src')

// Access to server cache dir
const cacheStorage = useStorage('cache')

// Access to the temp build dir
const buildStorage = useStorage('build')

In order to use the devStorage key, you need to use the nitro dev command and the key in the storage option must be the same as the production one.

export default defineNitroConfig({
  // Production
  storage: {
    db: {
      driver: 'redis',
      /* redis connector options */
    }
  },
  // Development
  devStorage: {
    db: {
      driver: 'fs',
      base: './data/db'
    }
  }
})

You will also be able to access to a build namespace in the storage layer only during development. It contains file generated by Nitro.