feat: migrate env-runner to 0.2 with explicit deps

Author: pi0

docs/2.deploy/20.providers/cloudflare.md

@@ -311,6 +311,8 @@ defineHandler(async (event) => {
 
 In development mode, Nitro emulates the Cloudflare environment using [Miniflare](https://miniflare.dev/) (the same [`workerd`](https://github.com/cloudflare/workerd) runtime used by Wrangler and cloudflare workers in production). This means bindings are available natively from the request event — no separate proxy or `wrangler` installation is required.
 
+The [`miniflare`](https://www.npmjs.com/package/miniflare) package is owned by your project: Nitro resolves it from your `node_modules` and offers to install it on first use.
+
 To access bindings in dev mode, we first define them. You can do this in a `wrangler.jsonc`/`wrangler.json`/`wrangler.toml` file:
 
 ::code-group

package.json

@@ -72,7 +72,7 @@
     "consola": "^3.4.2",
     "crossws": "^0.4.12",
     "db0": "^0.3.4",
-    "env-runner": "^0.1.16",
+    "env-runner": "^0.2.0",
     "h3": "^2.0.1-rc.29",
     "hookable": "^6.1.1",
     "nf3": "^0.3.23",

pnpm-lock.yaml

@@ -7,6 +7,7 @@ import { join, resolve } from "node:path";
 import { runtimeDependencies, runtimeDir } from "nitro/meta";
 import { resolveModulePath } from "exsolve";
 import { isAbsolute } from "pathe";
+import { resolveMiniflareDeps, resolveRunnerDeps } from "../../dev/runner-deps.ts";
 
 export function createNitroEnvironment(ctx: NitroPluginContext): EnvironmentOptions {
   const isWorkerdRunner = _isWorkerdRunner(ctx);
@@ -170,8 +171,11 @@ async function _loadRunner(ctx: NitroPluginContext, manager: RunnerManager) {
   let runner;
   if (runnerName === "miniflare") {
     const { MiniflareEnvRunner } = await import("env-runner/runners/miniflare");
+    const { miniflare, wranglerModule } = await resolveMiniflareDeps(ctx.nitro!);
     runner = new MiniflareEnvRunner({
       name: "nitro-vite",
+      miniflare,
+      wranglerModule,
       wrangler: {
         ...ctx.nitro!.options.cloudflare?.wrangler,
       },
@@ -180,6 +184,7 @@ async function _loadRunner(ctx: NitroPluginContext, manager: RunnerManager) {
     });
   } else {
     runner = await loadRunner(runnerName, {
+      ...(await resolveRunnerDeps(ctx.nitro!, runnerName)),
       name: "nitro-vite",
       data: { entry },
     });

src/build/vite/env.ts

@@ -0,0 +1,59 @@
+import type { RunnerName } from "env-runner";
+import type { Nitro } from "nitro/types";
+
+import { pathToFileURL } from "node:url";
+import { resolveModulePath } from "exsolve";
+import { ensureDep } from "../utils/dep.ts";
+
+export interface MiniflareRunnerDeps {
+  miniflare?: URL;
+  wranglerModule?: URL;
+  [key: string]: unknown;
+}
+
+/**
+ * Resolve the platform packages a dev runner needs from the user project.
+ *
+ * Runners do not import these packages themselves: each one is passed as an
+ * explicit option so the version installed next to the app is the version that
+ * runs. Unresolved entries are left out and the runner falls back to its own
+ * optional import (or a degraded mode).
+ */
+export async function resolveRunnerDeps(
+  nitro: Nitro,
+  runner: RunnerName
+): Promise<Record<string, unknown>> {
+  switch (runner) {
+    case "miniflare": {
+      return resolveMiniflareDeps(nitro);
+    }
+    case "netlify": {
+      // `@netlify/runtime` is instantiated inside the worker thread, so it can
+      // only be handed over as a specifier, never as an imported module.
+      return { netlifyRuntime: _resolve("@netlify/runtime", nitro.options.rootDir) };
+    }
+    default: {
+      return {};
+    }
+  }
+}
+
+export async function resolveMiniflareDeps(nitro: Nitro): Promise<MiniflareRunnerDeps> {
+  const miniflare = await ensureDep({
+    id: "miniflare",
+    dir: nitro.options.rootDir,
+    reason: "the `miniflare` dev runner",
+    version: "^4",
+  });
+  return {
+    miniflare: miniflare ? pathToFileURL(miniflare) : undefined,
+    // Optional: without it, a built-in minimal reader handles plain JSON
+    // wrangler configs and inline objects.
+    wranglerModule: _resolve("wrangler", nitro.options.rootDir),
+  };
+}
+
+function _resolve(id: string, dir: string): URL | undefined {
+  const path = resolveModulePath(id, { from: [dir, import.meta.url], try: true });
+  return path ? pathToFileURL(path) : undefined;
+}

src/dev/runner-deps.ts

@@ -16,6 +16,7 @@ import { serve } from "srvx/node";
 import { debounce } from "perfect-debounce";
 import { isTest, isCI } from "std-env";
 import { NitroDevApp } from "./app.ts";
+import { resolveRunnerDeps } from "./runner-deps.ts";
 import { writeDevBuildInfo } from "../build/info.ts";
 
 const SHUTDOWN_TIMEOUT = 5000;
@@ -189,9 +190,11 @@ export class NitroDevServer extends NitroDevApp implements RunnerRPCHooks {
 
   async #reload() {
     await this.#shutdownWorker();
-    const runnerName =
-      this.nitro.options.devServer.runner || process.env.NITRO_DEV_RUNNER || "node-worker";
-    const runner = await loadRunner(runnerName as RunnerName, {
+    const runnerName = (this.nitro.options.devServer.runner ||
+      process.env.NITRO_DEV_RUNNER ||
+      "node-worker") as RunnerName;
+    const runner = await loadRunner(runnerName, {
+      ...(await resolveRunnerDeps(this.nitro, runnerName)),
       name: `Nitro_${this.#workerIdCtr++}`,
       data: { entry: this.#entry, ...this.#workerData },
     });

src/dev/server.ts

@@ -1,3 +1,4 @@
+import * as queueSdk from "@vercel/queue";
 import { send } from "@vercel/queue";
 import { useRuntimeConfig } from "nitro/runtime-config";
 import { registerVercelQueueConsumer } from "env-runner/runners/vercel/queue-dev";
@@ -25,6 +26,8 @@ const queueDevPlugin: NitroAppPlugin = (nitroApp) => {
   const ready = Promise.all(
     triggers.map((trigger) =>
       registerVercelQueueConsumer({
+        // The SDK is owned by the app, so hand env-runner the instance we bundled.
+        sdk: queueSdk,
         topic: trigger.topic,
         retryAfterSeconds: trigger.retryAfterSeconds,
         handler: async (message: unknown, metadata: unknown) => {