Library / SDK
unjs/unstorage avatar
unjs/unstorage

unstorage ships no CommonJS entry, generates its drivers before every build, and sits two alphas past its own newest tag

💾 Unstorage provides an async Key-Value storage API with conventional features like multi driver mounting, watching and working with metadata, dozens of built-in drivers and a tiny core.

2,665 stars212 forksTypeScriptMIT

At a glance

What is it?
An async key-value layer with dozens of drivers, unix-style mounting and an in-memory default, small enough to tree shake. The interesting parts are in the packaging: an ESM-only manifest, a driver generator handed straight to node as a TypeScript file, and a version number already ahead of anything published.
Who is it for?
unstorage earns its place if your storage target changes between environments, since mounting a driver under a prefix and reading every target through one async API removes the per-target call sites. Four things to check before you adopt it.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 16, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • unjs/unstorage2,665 ★ · +13
Star history
Repository2026-10-042026-11-16
unjs/unstorage2.7k2.7k

13 Stars in the last 43 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The manifest reads 2.0.0-alpha.10 while the newest tag is v2.0.0-alpha.8

package.json declares version 2.0.0-alpha.10. The newest release tag is v2.0.0-alpha.8, published on 2026-08-20, so the working tree is already two alphas ahead of anything a consumer can install from a tag. The order of the three most recent releases says more than the version numbers do. v2.0.0-alpha.7 shipped on 2026-03-19, then v1.17.5 shipped on 2026-03-26, a week later on the stable 1.x line, and the next 2.0 alpha did not appear until 2026-08-20. Both lines are cut from the same main branch, and 1.x was still collecting patches while the 2.0 line sat untouched for five months. The last push to main is dated 2026-09-24, three weeks after the newest tag.

One release script, and it hardcodes the alpha tag

There is exactly one release path in the manifest, and it ends on the alpha tag:

code
"release": "pnpm test && pnpm build && changelogen --prerelease --release && pnpm publish --tag alpha",

Four gates in order. `pnpm test` is not only tests, it runs lint, then a type check, then the suite with coverage. `pnpm build` regenerates the drivers before compiling anything. `changelogen --prerelease --release` writes the changelog entry, and the publish step hardcodes the alpha tag. Nothing in this manifest can therefore put a build on the stable dist-tag on its own, even though v1.17.5 exists as a released version. `prepack` is set to `pnpm build`, so generation and compilation run again before anything is packed.

The contribution notes say jest, the dev script runs vitest

The contribution section tells you to use `pnpm dev` to start a jest watcher. The manifest defines that script as `vitest`, so the runner named in the prose is not the one that runs. It is not the only tool in the check either. Linting is `oxlint . && oxfmt --check .`, with .oxlintrc.json and .oxfmtrc.json at the root and no eslint configuration in the tree. Types are checked separately by `tsc --noEmit --skipLibCheck`, and only then does the suite run with coverage. The `fmt` script is the same two tools in fix mode, oxlint with --fix followed by oxfmt. A green `pnpm test` therefore means four separate things passed, and the order matters: a formatting difference stops the run before a single assertion is evaluated.

Drivers are generated by a TypeScript file node runs directly

Compiling this package begins by generating code rather than compiling what sits in src/. The build script is `pnpm gen-drivers && obuild`, and gen-drivers is `node scripts/gen-drivers.ts`. A TypeScript file is handed straight to node with no loader flag and no prior compile step, which only works on a Node release that strips types on its own. The benchmark takes the same route, `node test/server.bench.ts`, and lives under test/ rather than in a separate benches directory. One detail to note before trusting the front page. The README carries npm version, npm downloads, Codecov and bundlephobia minzip badges, and a GitHub Actions badge that is present in the markup but commented out, so the build status of the default branch is not surfaced there.

Every export resolves to .mjs, and only one of them declares its types

The package is ESM only and the manifest makes that explicit. `"type": "module"`, `main` points at ./dist/index.mjs, and every entry in the exports map resolves to an .mjs file, so there is no require entry anywhere. Types are handled two different ways. The root export is the plain string `./dist/index.mjs` with no types condition, leaving declaration resolution to the top-level `types` field at ./dist/index.d.mts. The `./tracing` subpath instead spells both conditions out, types first and default second. And `./drivers/*` maps straight to `./dist/drivers/*.mjs` with no types entry at all, so importing an individual driver resolves to a runtime file whose declaration the exports map never names. The published file list is one entry, dist, and the manifest is marked sideEffects false to keep the core tree shakeable.

getItem takes a colon key and a slash path on the same call

The one API call the documentation shows is doing more than it appears to:

js
import { createStorage } from "unstorage";

const storage = createStorage(/* opts */);

await storage.getItem("foo:bar"); // or storage.getItem('/foo/bar')

The same method takes a colon-separated key and a slash-separated path, so the separator is a per-call decision rather than a property fixed at mount time. That matters because the rest of the feature list rests on unix-style driver mounting: several storages get prefixed and combined into one namespace, and a leading slash reads as a path under the mount root. Around that sit auto JSON serialization, binary and raw value support, state snapshots with hydration, a storage watcher, and an HTTP storage with a built-in server. The options passed to createStorage appear in the snippet only as a comment, so no option name is given here.

The test environment expects live Upstash, Vercel, Cloudflare and UploadThing credentials

The repository carries a blank credential template. .env.example names eight variables and every one is empty: VITE_UPSTASH_REDIS_REST_URL and VITE_UPSTASH_REDIS_REST_TOKEN, VITE_VERCEL_BLOB_READ_WRITE_TOKEN with a private blob counterpart, three Cloudflare values for account id, KV namespace id and token, and VITE_UPLOADTHING_TOKEN. The VITE_ prefix matters, since that is the prefix the bundler substitutes into client code, which treats these as browser-visible values even though they authorise server-side services. vite.config.mjs sits at the root next to wrangler.toml and vercel.json, so one checkout is wired for three hosting targets at the same time. The devDependencies back that up: @azure/cosmos, @azure/data-tables, @azure/keyvault-secrets, @azure/storage-blob, @deno/kv, @electric-sql/pglite, @libsql/client, @netlify/blobs, @planetscale/database, @upstash/redis and @vercel/blob all appear there, with renovate.json at the root to keep them current.

Editorial conclusion

unstorage earns its place if your storage target changes between environments, since mounting a driver under a prefix and reading every target through one async API removes the per-target call sites. Four things to check before you adopt it. There is no CommonJS entry, so a require based build needs a bundler that resolves ESM. The root export carries no types condition and the drivers glob maps straight to a .mjs file, so declaration coverage per driver is uneven. The only release script in the manifest publishes to the alpha tag, and the manifest already reads 2.0.0-alpha.10 while the newest tag is v2.0.0-alpha.8, so pin what you install. And the default mount is in-memory, so nothing outlives the process until a real driver is attached. The last push to main is dated 2026-09-24.

Frequently asked questions

What does unstorage use as its default storage?

The default mount is in-memory, so a createStorage call with no driver attached keeps values for the life of the process. Persistent targets have to be mounted explicitly, and unix-style mounting lets several drivers be prefixed and combined into a single namespace.

Can I use unstorage from CommonJS?

Not from the manifest as published. The package sets type to module, main points at ./dist/index.mjs, and every entry in the exports map resolves to an .mjs file, so no require entry is declared anywhere in the package.

How do I try unstorage changes before they are released?

The project publishes a nightly channel under the package name unstorage-nightly. Alias your own dependency to it with "unstorage": "npm:unstorage-nightly" inside devDependencies, or override the same package in the resolutions field when unstorage reaches you through another tool.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. unjs/unstorage on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/unjs-unstorage.svg)](https://hysenlabs.com/projects/unjs-unstorage)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/unjs-unstorage.svg)](https://hysenlabs.com/projects/unjs-unstorage)

Was this useful?