feat: prompt to install storage driver dependencies

Author: pi0

docs/1.docs/8.storage.md

@@ -101,6 +101,12 @@ Then, you can use the redis storage using the `useStorage("redis")` function.
 You can find the driver list on [unstorage documentation](https://unstorage.unjs.io/) with their configuration.
 ::
 
+### Driver dependencies
+
+Some drivers rely on a third-party library (for example, `redis` requires [`ioredis`](https://www.npmjs.com/package/ioredis)).
+
+Nitro detects the libraries required by the mounted drivers and prompts to install the missing ones (installed automatically in CI). Installed libraries are then explicitly passed to the driver via its `lib` option, so that bundlers can statically resolve them.
+
 ### Development storage
 
 You can use the `devStorage` option to override storage configuration during development and prerendering.

package.json

@@ -82,7 +82,7 @@
     "rou3": "^0.9.2",
     "srvx": "^0.12.7",
     "unenv": "^2.0.0-rc.24",
-    "unstorage": "^2.0.0-alpha.7"
+    "unstorage": "^2.0.0-alpha.8"
   },
   "devDependencies": {
     "@apphosting/common": "^0.0.9",

pnpm-lock.yaml

@@ -1,26 +1,13 @@
 import { genImport, genSafeVariableName } from "knitwork";
 import type { Nitro } from "nitro/types";
-import { builtinDrivers } from "unstorage";
+import { isDepInstalled } from "../../utils/dep.ts";
+import { isLibOption, resolveDriverDeps, resolveStorageMounts } from "../../utils/storage.ts";
 
 export default function storage(nitro: Nitro) {
   return {
     id: "#nitro/virtual/storage",
     template: () => {
-      const mounts: { path: string; driver: string; opts: object }[] = [];
-
-      const isDevOrPrerender = nitro.options.dev || nitro.options.preset === "nitro-prerender";
-      const storageMounts = isDevOrPrerender
-        ? { ...nitro.options.storage, ...nitro.options.devStorage }
-        : nitro.options.storage;
-
-      for (const path in storageMounts) {
-        const { driver: driverName, ...driverOpts } = storageMounts[path];
-        mounts.push({
-          path,
-          driver: builtinDrivers[driverName as keyof typeof builtinDrivers] || driverName,
-          opts: driverOpts,
-        });
-      }
+      const mounts = resolveStorageMounts(nitro.options);
 
       const driverImports = [...new Set(mounts.map((m) => m.driver))];
 
@@ -41,7 +28,7 @@ export function initStorage() {
   ${mounts
     .map(
       (m) =>
-        `storage.mount('${m.path}', ${genSafeVariableName(m.driver)}(${JSON.stringify(m.opts)}))`
+        `storage.mount('${m.path}', ${genSafeVariableName(m.driver)}(${genDriverOptions(nitro, m)}))`
     )
     .join("\n")}
   return ${tracingEnabled ? "withTracing(storage)" : "storage"}
@@ -50,3 +37,21 @@ export function initStorage() {
     },
   };
 }
+
+/**
+ * Explicitly provide third-party libraries used by the driver via the `lib` option
+ * so that they are statically analyzable by the bundler.
+ */
+function genDriverOptions(nitro: Nitro, mount: ReturnType<typeof resolveStorageMounts>[number]) {
+  const libs = resolveDriverDeps(mount.name)
+    .filter(
+      (dep) =>
+        isLibOption(dep.option) &&
+        mount.options[dep.option] === undefined &&
+        isDepInstalled(dep.name, nitro.options.rootDir)
+    )
+    .map((dep) => `${dep.option}: () => import(${JSON.stringify(dep.name)})`);
+
+  const options = JSON.stringify(mount.options);
+  return libs.length > 0 ? `{ ...${options}, ${libs.join(", ")} }` : options;
+}

src/build/virtual/storage.ts

@@ -1,5 +1,34 @@
+import consola from "consola";
 import type { NitroOptions } from "nitro/types";
+import { ensureDep } from "../../utils/dep.ts";
+import { resolveDriverDeps, resolveStorageMounts } from "../../utils/storage.ts";
 
 export async function resolveStorageOptions(options: NitroOptions) {
-  //
+  // Storage drivers lazily import their third-party dependencies.
+  // Make sure the ones required by the configured mounts are installed.
+  const deps = new Map<string, { version?: string; drivers: Set<string> }>();
+  for (const mount of resolveStorageMounts(options)) {
+    for (const dep of resolveDriverDeps(mount.name)) {
+      if (dep.optional || mount.options[dep.option] !== undefined) {
+        continue; // Not required or explicitly provided by the user
+      }
+      const entry = deps.get(dep.name) || { version: dep.version, drivers: new Set() };
+      entry.drivers.add(mount.name);
+      deps.set(dep.name, entry);
+    }
+  }
+
+  for (const [name, { version, drivers }] of deps) {
+    const reason = `the ${[...drivers].map((d) => `\`${d}\``).join(", ")} storage driver${drivers.size > 1 ? "s" : ""}`;
+    const resolved = await ensureDep({
+      id: name,
+      version,
+      dir: options.rootDir,
+      reason,
+      dev: false,
+    });
+    if (!resolved) {
+      consola.warn(`\`${name}\` is not installed. It is required for ${reason}.`);
+    }
+  }
 }

src/config/resolvers/storage.ts

@@ -2,22 +2,33 @@ import { consola } from "consola";
 import { resolveModulePath } from "exsolve";
 import { isCI, isTest } from "std-env";
 
-export async function importDep<T>(
-  opts: {
-    id: string;
-    dir: string;
-    reason: string;
-  },
-  _retry?: boolean
-): Promise<T> {
+export interface DepOptions {
+  /** Package name to resolve and install. */
+  id: string;
+  /** Directory to resolve from and install into. */
+  dir: string;
+  /** Human readable reason, used in prompts and errors. */
+  reason: string;
+  /** Version range used when installing (ignored if it is not a simple range). */
+  version?: string;
+  /** Install as a dev dependency. (default: `true`) */
+  dev?: boolean;
+}
+
+/**
+ * Ensure a dependency is installed, prompting to install it if missing.
+ *
+ * Resolves to the module path or `undefined` if it is (still) not available.
+ */
+export async function ensureDep(opts: DepOptions, _retry?: boolean): Promise<string | undefined> {
   const resolved = resolveModulePath(opts.id, {
     from: [opts.dir, import.meta.url],
     cache: _retry ? false : true,
     try: true,
   });
 
   if (resolved) {
-    return (await import(resolved)) as Promise<T>;
+    return resolved;
   }
 
   let shouldInstall: boolean | undefined;
@@ -36,16 +47,29 @@ export async function importDep<T>(
   }
 
   if (!shouldInstall) {
-    throw new Error(
-      `\`${opts.id}\` is not installed. Please add it to your dependencies for ${opts.reason}.`
-    );
+    return undefined;
   }
 
   const start = Date.now();
   consola.start(`Installing \`${opts.id}\` in \`${opts.dir}\`...`);
-  const { addDevDependency } = await import("nypm");
-  await addDevDependency(opts.id, { cwd: opts.dir });
+  const { addDependency, addDevDependency } = await import("nypm");
+  const spec = opts.version && !opts.version.includes(" ") ? `${opts.id}@${opts.version}` : opts.id;
+  await (opts.dev === false ? addDependency : addDevDependency)(spec, { cwd: opts.dir });
   consola.success(`Installed \`${opts.id}\` in ${opts.dir} (${Date.now() - start}ms).`);
 
-  return importDep<T>(opts, true);
+  return ensureDep(opts, true);
+}
+
+export async function importDep<T>(opts: DepOptions): Promise<T> {
+  const resolved = await ensureDep(opts);
+  if (!resolved) {
+    throw new Error(
+      `\`${opts.id}\` is not installed. Please add it to your dependencies for ${opts.reason}.`
+    );
+  }
+  return (await import(resolved)) as T;
+}
+
+export function isDepInstalled(id: string, dir: string): boolean {
+  return !!resolveModulePath(id, { from: [dir, import.meta.url], try: true });
 }

src/utils/dep.ts

@@ -0,0 +1,52 @@
+import type { NitroOptions } from "nitro/types";
+import { builtinDriverDependencies, builtinDrivers } from "unstorage";
+import type { BuiltinDriverName } from "unstorage";
+
+export interface StorageMount {
+  /** Mount point path. */
+  path: string;
+  /** Driver name as configured by the user. */
+  name: string;
+  /** Module id to import the driver from. */
+  driver: string;
+  /** Driver options. */
+  options: Record<string, any>;
+}
+
+export interface StorageDriverDep {
+  /** Driver option the library can be provided with (e.g. `lib`). */
+  option: string;
+  /** Package name. */
+  name: string;
+  /** Supported version range. */
+  version?: string;
+  /** Only required for some of the driver features. */
+  optional?: boolean;
+}
+
+/** Resolve storage mounts that will be used for the current build. */
+export function resolveStorageMounts(options: NitroOptions): StorageMount[] {
+  const isDevOrPrerender = options.dev || options.preset === "nitro-prerender";
+  const mounts = isDevOrPrerender ? { ...options.storage, ...options.devStorage } : options.storage;
+  return Object.entries(mounts).map(([path, { driver: name, ...driverOpts }]) => ({
+    path,
+    name,
+    driver: builtinDrivers[name as BuiltinDriverName] || name,
+    options: driverOpts,
+  }));
+}
+
+/**
+ * Third-party dependencies of a builtin driver.
+ *
+ * Since `unstorage` v2, they are not declared as optional peer dependencies anymore.
+ */
+export function resolveDriverDeps(name: string): StorageDriverDep[] {
+  const deps = builtinDriverDependencies[name as BuiltinDriverName];
+  return Object.entries(deps || {}).map(([option, dep]) => ({ option, ...dep }));
+}
+
+/** Driver options accepting a library import (`lib`, `identityLib`, ...). */
+export function isLibOption(option: string): boolean {
+  return option === "lib" || option.endsWith("Lib");
+}