feat: install unstorage, db0 and ocache on demand

[pi0x]

unstorage, db0 and ocache are no longer dependencies of Nitro. They are resolved from the project and installed on demand, without prompting, like unenv now (ensureDep with the new autoInstall option; never in test mode), only when used:

	unstorage	db0	ocache
Config	kv mounts (or deprecated storage / devStorage)	experimental.database	—
Cache	cache.driver: "kv" (explicit or inferred from a cache mount)	—	—
Import	nitro/kv, nitro/storage	nitro/database	nitro/cache
Route rules	—	—	cache / swr rules (headers, redirect, ... do not import it)

Apps using none of these never resolve or install them.

Changes

• Config time: kv / cache / database resolvers import the package on demand. Driver and connector maps are no longer top-level imports (src/utils/storage.ts, src/utils/database.ts). The kv and database virtual templates are now async.
• Resolve time: new nitro:runtime-deps plugin (src/build/plugins/runtime-deps.ts) catches unstorage* / db0* / ocache* imports from Nitro runtime and virtual modules, ensures the package is installed and resolves it from the project. Used by rollup, rolldown and Vite; Vite dev no longer externalizes them. builder: false gets an env-runner fallback resolver.
• ensureDep: concurrent calls share one prompt/install. It no longer trusts exsolve's cached failed lookups, which previously caused repeated installs and, with nitro outside the project (pnpm global store, npm link), a build that exited 0 with unstorage left unresolved. isDepInstalled uses the same lookup, and the version check runs once per package.
• Shared with the unenv on-demand install:
  • One missing-dependency error with a versioned install command (missingDepError). unenv's previous hint (npx nypm add -D unenv) installed unenv v1.
  • The version check now covers prerelease (^2.0.0-rc.24) and 0.x (^0.4.1) ranges. Before, it skipped unenv, unstorage and db0 entirely.
  • The unenv plugin no longer remembers its install result, so nitro dev picks up a manual install without a restart.
  • A successful install is no longer logged when the package still can't be resolved.
• Types: config types fall back when the packages are not installed (OptionalDepType, and Partial for the cache defaults); .d.mts imports are @ts-ignored via optionalTypeDeps. Inline import("ocache") types became named type imports, which the .d.mts step requires.
• server-assets inlines normalizeKey.
• runtimeDependencies (nitro/meta) no longer lists unstorage / db0 / ocache. Nuxt reads this list and already adds unstorage itself, so db0 and ocache drop out of its optimizeDeps.exclude.
• Docs (storage, database, cache, migration) and examples updated.

Tests

• test/unit/build-runtime-deps.test.ts: each trigger on rollup and rolldown, "not used" builds, missing-package error, no uncached lookups, and a source guard against build-time value imports.
• test/unit/dep.test.ts: install once, recover after a failed or manual install, concurrent calls share one install, cached lookups, version checked once.
• Unbundled: a /kv route and a direct test of the fallback resolver.
• Manually verified with nitro in an external store and a fake npm: one install per package and a working build output, on both builders (for ocache: a defineCachedFunction app installs it once and the built server serves the cached value).

🤖 Generated with AI assistant

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
nitro.build	Ready	Preview	Oct 18, 2026 2:08am UTC

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 106cec0c-73f4-4e4a-bc4d-a0a83cb60cce

📥 Commits

Reviewing files that changed from the base of the PR and between 8a6b16f and 58d4fb4.

⛔ Files ignored due to path filters: 1

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing: 39

• .agents/architecture.md
• build.config.ts
• docs/1.docs/50.database.md
• docs/1.docs/7.cache.md
• docs/1.docs/8.storage.md
• docs/1.docs/99.migration.md
• docs/4.examples/cached-handler.md
• docs/4.examples/database.md
• docs/4.examples/tracing.md
• docs/4.examples/vitest.md
• examples/cached-handler/package.json
• examples/database/package.json
• examples/tracing/package.json
• examples/vitest/package.json
• package.json
• src/build/plugins.ts
• src/build/plugins/runtime-deps.ts
• src/build/plugins/unenv.ts
• src/build/unbundled/plugins.ts
• src/build/virtual/database.ts
• src/build/virtual/kv.ts
• src/build/virtual/server-assets.ts
• src/build/vite/env.ts
• src/config/resolvers/cache.ts
• src/config/resolvers/database.ts
• src/config/resolvers/kv.ts
• src/runtime/_meta.ts
• src/types/config.ts
• src/types/runtime/cache.ts
• src/utils/database.ts
• src/utils/dep.ts
• src/utils/storage.ts
• test/unbundled/fixture/routes/kv.ts
• test/unbundled/unbundled.test.ts
• test/unit/build-runtime-deps.test.ts
• test/unit/build-unenv.test.ts
• test/unit/dep.test.ts
• test/unit/virtual-database.test.ts
• test/unit/virtual-kv.test.ts

+-------------------------+
| No pants, fast results! |
+-------------------------+
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4764

commit: 58d4fb4

[pi0]

Merging to experience effect e2e. if too much downsides, we will add back default deps as they are fairly small.