Skip to content

Commit f240faf

Browse files
docs: show custom storage driver from interface, not wrap
Address review feedback: from-scratch drivers implement the unstorage interface; wrapping is only for patching existing drivers. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent dc5fd65 commit f240faf

1 file changed

Lines changed: 33 additions & 14 deletions

File tree

docs/1.docs/8.storage.md

Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -105,42 +105,61 @@ You can find the driver list on [unstorage documentation](https://unstorage.unjs
105105

106106
The `driver` field accepts a built-in driver name (for example `"redis"`) or a **path** to a custom driver module. You cannot pass a driver function or object directly in config — Nitro imports drivers as separate modules so your config stays separate from runtime code.
107107

108-
Create a driver file that default-exports a driver created with `defineDriver`:
108+
Create a driver file that **default-exports** a driver factory from `defineDriver`. To build a driver from scratch, implement the [unstorage driver interface](https://unstorage.unjs.io/guide/custom-driver) (`hasItem`, `getItem`, `setItem`, and so on):
109109

110-
```ts [drivers/upstash.ts]
110+
```ts [drivers/kv.ts]
111111
import { defineDriver } from "unstorage";
112-
import { upstashDriver } from "unstorage/drivers/upstash";
113112

114-
export default defineDriver((opts = {}) => {
115-
const driver = upstashDriver(opts);
113+
export default defineDriver((opts: { prefix?: string } = {}) => {
114+
const data = new Map<string, string>();
115+
const prefix = opts.prefix || "";
116+
116117
return {
117-
...driver,
118-
async setItem(key, value, opts) {
119-
const ttl = opts?.ttl ? { ...opts, ttl: Math.ceil(opts.ttl / 1000) } : opts;
120-
return driver.setItem!(key, value, ttl);
118+
name: "kv",
119+
options: opts,
120+
hasItem(key) {
121+
return data.has(prefix + key);
122+
},
123+
getItem(key) {
124+
return data.get(prefix + key) ?? null;
125+
},
126+
setItem(key, value) {
127+
data.set(prefix + key, value);
128+
},
129+
removeItem(key) {
130+
data.delete(prefix + key);
131+
},
132+
getKeys() {
133+
return [...data.keys()].map((k) =>
134+
prefix ? k.slice(prefix.length) : k,
135+
);
136+
},
137+
clear() {
138+
data.clear();
121139
},
122140
};
123141
});
124142
```
125143

126-
Reference it by path in your Nitro config:
144+
Reference it by path in your Nitro config (options besides `driver` are passed into the factory):
127145

128146
```ts [nitro.config.ts]
129147
import { defineConfig } from "nitro";
130148

131149
export default defineConfig({
132150
storage: {
133-
upstash: {
134-
driver: "./drivers/upstash.ts",
135-
url: process.env.KV_REST_API_URL,
136-
token: process.env.KV_REST_API_TOKEN,
151+
kv: {
152+
driver: "./drivers/kv.ts",
153+
prefix: "app:",
137154
},
138155
},
139156
});
140157
```
141158

142159
Use a path relative to your project root (or an absolute path). Nitro bundles the driver for the server runtime.
143160

161+
To **patch** an existing unstorage driver instead of writing one from scratch, wrap it inside `defineDriver`, spread the base driver, and override only the methods you need.
162+
144163
:read-more{to="https://unstorage.unjs.io/guide/custom-driver" title="unstorage custom driver guide"}
145164

146165
### Development storage

0 commit comments

Comments
 (0)