Custom drivers

[maximelebreton]

Hello Nitro team!

Expected behavior

I would expect Nitro to support custom driver functions or objects in the storage configuration, not just string identifiers.

Or clarify the documentation that only string identifiers for built-in drivers are supported in nuxt.config.ts: https://unstorage.unjs.io/guide/custom-driver

---

Describe the bug

When configuring a custom storage driver for Nitro in nuxt.config.ts using defineDriver, Nitro tries to resolve the driver function or object as a package. This results in an error like:

// with driver: upstashCustomDriver()
Cannot find package [object Object]' imported from node_modules/.../nitropack/dist/core/index.mjs

// with driver: upstashCustomDriver
Cannot find package '(opts = {}) => { … }' imported from node_modules/.../nitropack/dist/core/index.mjs

Currently, only string identifiers for built-in drivers (e.g. 'redis', 'memory') work in the config.

---

Environment

• Nuxt / Nitro version: 3.x / 2.x
• Deployment: Vercel serverless
• Storage: Custom Unstorage driver based on Upstash

---

Reproduction

// drivers/upstashCustomDriver.ts
import { defineDriver } from 'unstorage';
import { upstashDriver } from 'unstorage/drivers';

export const upstashCustomDriver = defineDriver((opts = {}) => {
  const driver = upstashDriver(opts);
  return {
    ...driver,
    async setItem(key: string, value: any, opts?: { ttl?: number }) {
      const modifiedOpts = opts?.ttl ? { ...opts, ttl: Math.ceil(opts.ttl / 1000) } : opts;
      return driver.setItem!(key, value, modifiedOpts);
    }
  };
});

// nuxt.config.ts
import { upstashCustomDriver } from './drivers/upstashCustomDriver';

export default defineNuxtConfig({
  nitro: {
    storage: {
      upstash: {
        driver: upstashCustomDriver(), // ❌ causes error on Vercel
        //driver: upstashCustomDriver, // ❌ causes error too
        url: process.env.KV_REST_API_URL,
        token: process.env.KV_REST_API_TOKEN
      }
    }
  }
});

[danielroe]

string identifiers (but this does include passing a path to a custom driver) are required as they become part of your runtime code and we want a hard separation between your config and your code

[maximelebreton]

@danielroe thanks for your response!
But so, could you clarify how to declare a custom driver to be imported as a string in nuxt.config.ts?

I couldn't fin any documentation for the “string” method in Nuxt or Unstorage:
https://unstorage.unjs.io/guide/custom-driver

It would be really helpful to have an example for non experts like me :)

[pi0]

It is possible to pass the full path to drivers by setting driver to the absolute path of a custom driver (v2 src, v3 src)

Example:

export default defineNuxtConfig({
  nitro: {
    storage: {
      upstash: {
        driver: './drivers/upstashCustomDriver.ts'
        url: process.env.KV_REST_API_URL,
        token: process.env.KV_REST_API_TOKEN
      }
    }
  }

The main limitation in Nitro v2 (current Nuxt), was that runtime code in the driver entry is loaded both in the builder (Node.js) and in the server runtime. It is no longer an issue in Nitro v3 (future Nuxt) as Nitro only imports drivers in the runtime namespace where builder is available, so all runtime features are available.

I think we should improve both docs with some examples.

[maximelebreton]

Thank you @pi0

Just to be sure, could you please confirm that the TypeScript file should look like this?

// drivers/upstashCustomDriver.ts
import { defineDriver } from 'unstorage';
import { upstashDriver } from 'unstorage/drivers';

export default defineDriver((opts = {}) => {
  const driver = upstashDriver(opts);
  return {
    ...driver
    //... custom driver props
  };
});