/nitro

KV Storage

Nitro ships a runtime-agnostic key-value layer powered by unstorage. Access it with useStorage() from nitro/storage.

Usage

import { useStorage } from "nitro/storage";

// Default storage (in-memory, not persisted across restarts)
await useStorage().setItem("test:foo", { hello: "world" });
const value = await useStorage().getItem("test:foo");

// Scope to a base/mountpoint
const test = useStorage("test");
await test.setItem("foo", { hello: "world" });

// Type the return value
await useStorage<{ hello: string }>("test").getItem("foo");

Common methods

Aliases: get, set, has, del, remove, keys.

Configuring drivers

Mount drivers by name; the key is the mount point, the value is the driver config.

import { defineConfig } from "nitro";

export default defineConfig({
  storage: {
    redis: { driver: "redis", url: "redis://localhost:6379" },
    db: { driver: "redis", host: "prod.example.com" },
  },
  // Override mounts in dev (e.g. when the prod driver isn't available locally)
  devStorage: {
    db: { driver: "fs", base: "./.data/db" },
  },
});

Then useStorage("redis") / useStorage("db"). See the unstorage drivers list (fs, memory, redis, cloudflare-kv, s3, ...).

Built-in mount points

• Default (no base): in-memory, not persisted. Mount an fs/redis driver to persist.
• assets:server (a.k.a. assets/server): read-only access to bundled server assets — see core-assets.
• cache: used by the caching layer — see core-cache.

Runtime / dynamic mounts

When credentials are only known at runtime, mount a driver from a plugin:

import { definePlugin } from "nitro";
import { useStorage } from "nitro/storage";
import redisDriver from "unstorage/drivers/redis";

export default definePlugin(() => {
  const storage = useStorage();
  storage.mount("redis", redisDriver({
    base: "redis",
    host: process.env.REDIS_HOST,
    port: process.env.REDIS_PORT,
  }));
});

Key Points

• Import useStorage from nitro/storage (v2 path nitropack/runtime/storage is gone).
• Default storage is in-memory; configure a persistent driver via storage for production.
• Use devStorage to swap drivers in development without changing production config.
• Prefer this abstraction over platform-specific KV APIs (e.g. Cloudflare KV) for portability.