env-runner 0.1.15 → 0.2.0

package/dist/_chunks/miniflare-runner.d.mts

@@ -1,7 +1,21 @@
 import { WorkerHooks } from "./types.mjs";
 import { BaseEnvRunner, EnvRunnerData } from "./common-base-runner.mjs";
+import { RuntimeDep } from "./common-runtime-deps.mjs";
 import { IncomingMessage } from "node:http";
 import { Socket } from "node:net";
+/**
+ * The `wrangler` package, as imported by the consumer.
+ *
+ * `wrangler` is not a dependency of `env-runner` — pass the module namespace
+ * (`import * as wrangler from "wrangler"`) or a specifier for it, so the
+ * dependency stays owned by the application. It is only imported here as a
+ * fallback when neither is passed.
+ */
+interface WranglerModule {
+  unstable_readConfig?: (...args: any[]) => any;
+  unstable_getMiniflareWorkerOptions?: (...args: any[]) => any;
+  [key: string]: unknown;
+}
 /** Raw (snake_case) Wrangler config object, mirroring `wrangler.json` contents. */
 type WranglerInlineConfig = Record<string, unknown>;
 /** Result from a module transform (compatible with Vite's `TransformResult`). */
@@ -12,10 +26,45 @@ interface TransformResult {
 interface MiniflareExportInfo {
   type?: "DurableObject" | "WorkerEntrypoint" | "class";
 }
+/**
+ * The `miniflare` package, as imported by the consumer.
+ *
+ * `miniflare` is not a dependency of `env-runner` — pass the module namespace
+ * (`import * as miniflare from "miniflare"`) so the dependency stays owned by
+ * the application. The runner only falls back to importing it itself when this
+ * is omitted.
+ */
+interface MiniflareModule {
+  Miniflare: new (options: any) => any;
+  /**
+   * Newest compatibility date supported by the installed `workerd` binary,
+   * clamped to today. Used as the default `compatibilityDate`.
+   */
+  supportedCompatibilityDate?: string;
+  [key: string]: unknown;
+}
 interface MiniflareEnvRunnerOptions {
   name: string;
   hooks?: WorkerHooks;
   data?: EnvRunnerData;
+  /**
+   * The `miniflare` package: the imported module, or a specifier for it.
+   *
+   * ```ts
+   * import * as miniflare from "miniflare";
+   * new MiniflareEnvRunner({ name: "app", miniflare, data: { entry } });
+   *
+   * // or, equivalently
+   * new MiniflareEnvRunner({ name: "app", miniflare: "miniflare", data: { entry } });
+   * ```
+   *
+   * Passing it explicitly is preferred (`miniflare` is not a dependency of
+   * `env-runner`, so the version you install is the version that runs). Bare
+   * specifiers resolve from the current working directory. When omitted, the
+   * runner falls back to importing `miniflare` itself and only fails if that
+   * is unavailable too.
+   */
+  miniflare?: RuntimeDep<MiniflareModule>;
   /** Options passed directly to the Miniflare constructor. */
   miniflareOptions?: Record<string, unknown>;
   /**
@@ -68,12 +117,12 @@ interface MiniflareEnvRunnerOptions {
    *   merged on top of it (inline wins per key, binding records merge,
    *   `compatibilityFlags` are unioned).
    *
-   * The installed `wrangler` package is preferred (full fidelity: TOML,
+   * The `wrangler` package is used for full fidelity when available (TOML,
    * `env` inheritance, `.dev.vars`, every binding type; an inline config is
-   * normalized through a short-lived temp file). When `wrangler` is not
-   * installed, a built-in minimal reader handles plain JSON files and inline
-   * objects (common fields only) and a one-time warning is logged. JSONC and
-   * TOML files without `wrangler` are skipped with a warning. Values from
+   * normalized through a short-lived temp file) — passed explicitly as
+   * `wranglerModule`, or imported optionally. Otherwise a built-in minimal
+   * reader handles plain JSON files and inline objects (common fields only);
+   * JSONC and TOML files are skipped with a warning. Values from
    * `miniflareOptions` always win over config-derived ones; binding records
    * (e.g. `bindings`) merge per key and `compatibilityFlags` are unioned.
    */
@@ -83,6 +132,16 @@ interface MiniflareEnvRunnerOptions {
    * Defaults to the `CLOUDFLARE_ENV` environment variable.
    */
   wranglerEnv?: string;
+  /**
+   * The imported `wrangler` package (`import * as wrangler from "wrangler"`),
+   * used to parse the {@link MiniflareEnvRunnerOptions.wrangler} config with
+   * full fidelity. When omitted, `import("wrangler")` is tried, and a built-in
+   * minimal reader (plain JSON configs and inline objects) handles the rest.
+   *
+   * Pass `false` to skip the `wrangler` package entirely and always use the
+   * built-in minimal reader.
+   */
+  wranglerModule?: RuntimeDep<WranglerModule>;
 }
 declare class MiniflareEnvRunner extends BaseEnvRunner {
   #private;
@@ -124,4 +183,4 @@ declare class MiniflareEnvRunner extends BaseEnvRunner {
     };
   }): Promise<void>;
 }
-export { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, TransformResult, WranglerInlineConfig };
+export { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, MiniflareModule, TransformResult, WranglerInlineConfig, WranglerModule };

package/dist/_chunks/miniflare-runner.mjs

@@ -1,5 +1,6 @@
 import { expandVirtualInvalidation, stripVirtualTypeScript, virtualModuleFormat } from "./virtual-loader.mjs";
 import { BaseEnvRunner } from "./common-base-runner.mjs";
+import { resolveRuntimeDep } from "./common-runtime-deps.mjs";
 import { init, parse } from "./libs/cjs-module-lexer.mjs";
 import { init as init$1, parse as parse$1 } from "./libs/es-module-lexer.mjs";
 import { isVirtualSpecifier } from "./common-worker-utils.mjs";
@@ -7,8 +8,8 @@ import { createRequire } from "node:module";
 import { proxyUpgrade } from "httpxy";
 import { fileURLToPath } from "node:url";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { resolveModulePath } from "exsolve";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 const IPC_PATH = "/__env_runner_ipc";
 const IPC_BINDING = "__ENV_RUNNER_IPC";
@@ -180,10 +181,6 @@ export default {
 };
 `;
 }
-function importWrangler() {
-	return import("wrangler");
-}
-let _warnedNoWrangler = false;
 const WRANGLER_CONFIG_FILENAMES = [
 	"wrangler.json",
 	"wrangler.jsonc",
@@ -207,7 +204,7 @@ function isPlainObject(value) {
 function isInlineWranglerConfig(opt) {
 	return isPlainObject(opt);
 }
-async function loadWranglerConfig(opt, env, entryPath) {
+async function loadWranglerConfig(opt, env, entryPath, wranglerModule) {
 	if (!opt) return;
 	const inline = isInlineWranglerConfig(opt) ? opt : void 0;
 	let configPath;
@@ -224,16 +221,12 @@ async function loadWranglerConfig(opt, env, entryPath) {
 			return;
 		}
 	} else configPath = findWranglerConfig(entryPath);
-	let wrangler;
-	try {
-		wrangler = await importWrangler();
-	} catch {
-		if (!_warnedNoWrangler) {
-			_warnedNoWrangler = true;
-			console.warn("[env-runner] 'wrangler' is not installed; using the built-in minimal config reader (plain JSON, common fields only). Install 'wrangler' for full fidelity (JSONC, TOML, env inheritance, all binding types).");
-		}
-		return mergeWranglerMiniflareOptions(configPath ? readWranglerConfigMinimal(configPath, env) : void 0, inline ? mapWranglerConfigToMiniflare(applyWranglerEnv(inline, env)) : void 0);
-	}
+	const wrangler = await resolveRuntimeDep({
+		name: "wrangler",
+		option: "wranglerModule",
+		value: wranglerModule
+	});
+	if (!wrangler?.unstable_readConfig || !wrangler.unstable_getMiniflareWorkerOptions) return mergeWranglerMiniflareOptions(configPath ? readWranglerConfigMinimal(configPath, env) : void 0, inline ? mapWranglerConfigToMiniflare(applyWranglerEnv(inline, env)) : void 0);
 	try {
 		return mergeWranglerMiniflareOptions(configPath ? pickWranglerMiniflareOptions(wrangler.unstable_getMiniflareWorkerOptions(wrangler.unstable_readConfig({
 			config: configPath,
@@ -374,11 +367,14 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 	#exportConditions;
 	#wrangler;
 	#wranglerEnv;
+	#wranglerModule;
+	#miniflareModule;
 	constructor(opts) {
 		super({
 			...opts,
 			workerEntry: ""
 		});
+		this.#miniflareModule = opts.miniflare;
 		this.#miniflareOptions = opts.miniflareOptions || {};
 		this.#transformRequest = opts.transformRequest;
 		this.#persistent = opts.persistent ?? false;
@@ -387,6 +383,7 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 		this.#exportConditions = opts.exportConditions ?? ["workerd", "worker"];
 		this.#wrangler = opts.wrangler ?? false;
 		this.#wranglerEnv = opts.wranglerEnv ?? process.env.CLOUDFLARE_ENV;
+		this.#wranglerModule = opts.wranglerModule;
 		this._initWithVirtualData(() => this.#init());
 	}
 	static async disposeAll() {
@@ -482,6 +479,17 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 		} else await this.#miniflare.dispose();
 		this.#miniflare = void 0;
 	}
+	async #resolveMiniflare() {
+		this.#miniflareModule = await resolveRuntimeDep({
+			name: "miniflare",
+			option: "miniflare",
+			value: this.#miniflareModule,
+			expect: "Miniflare",
+			required: true,
+			hint: "MiniflareEnvRunner cannot run without it (`import * as miniflare from \"miniflare\"`)."
+		});
+		return this.#miniflareModule;
+	}
 	#init() {
 		this.#initAsync().catch((error) => {
 			console.error("Miniflare runner init error:", error);
@@ -517,11 +525,11 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 		});
 	}
 	async #initAsync() {
-		const { Miniflare, supportedCompatibilityDate } = await import("miniflare");
+		const { Miniflare, supportedCompatibilityDate } = await this.#resolveMiniflare();
 		const entryPath = this._data?.entry;
 		const virtual = await this.#prepareVirtualModules();
 		this.#virtual = virtual;
-		const wranglerOptions = await loadWranglerConfig(this.#wrangler, this.#wranglerEnv, entryPath);
+		const wranglerOptions = await loadWranglerConfig(this.#wrangler, this.#wranglerEnv, entryPath, this.#wranglerModule);
 		const userFlags = this.#miniflareOptions.compatibilityFlags || [];
 		const wranglerFlags = wranglerOptions?.compatibilityFlags || [];
 		const userDirectSockets = this.#miniflareOptions.unsafeDirectSockets || [];
@@ -662,7 +670,8 @@ var MiniflareEnvRunner = class extends BaseEnvRunner {
 						}
 					} else {
 						const referrerKey = referrer.startsWith("/") ? referrer.slice(1) : referrer;
-						const referrerDir = dirname(modulePathMap.get(referrerKey) || (referrer.startsWith("/") ? referrer : "/" + referrer));
+						const referrerReal = modulePathMap.get(referrerKey) || (referrer.startsWith("/") ? referrer : "/" + referrer);
+						const referrerDir = dirname(referrerReal);
 						const raw = cleanRaw || cleanSpecifier;
 						if (raw.startsWith(".")) resolvedPath = resolve(referrerDir, raw);
 						else if (cleanSpecifier.startsWith("/")) resolvedPath = cleanSpecifier;

package/dist/_chunks/netlify-runner.d.mts

@@ -1,14 +1,39 @@
 import { WorkerHooks } from "./types.mjs";
 import { EnvRunnerData } from "./common-base-runner.mjs";
 import { NodeWorkerEnvRunner } from "./node-worker-runner.mjs";
+interface NetlifyEnvRunnerOptions {
+  name: string;
+  workerEntry?: string;
+  hooks?: WorkerHooks;
+  data?: EnvRunnerData;
+  /**
+   * Module specifier for the `@netlify/runtime` package, used inside the
+   * worker to call `startRuntime()` (full `globalThis.Netlify` + `caches`
+   * setup). `env-runner` does not depend on `@netlify/runtime`.
+   *
+   * Unlike the other runtime-dependency options, this one takes a **specifier
+   * only**: the runtime has to be instantiated inside the worker thread, and a
+   * live module instance cannot cross that boundary.
+   *
+   * ```ts
+   * new NetlifyEnvRunner({
+   *   name: "app",
+   *   netlifyRuntime: import.meta.resolve("@netlify/runtime"),
+   *   data: { entry },
+   * });
+   * ```
+   *
+   * A bare specifier (e.g. `"@netlify/runtime"`) is resolved from the current
+   * working directory. When omitted, the worker tries
+   * `import("@netlify/runtime")` and falls back to a lightweight
+   * `globalThis.Netlify` shim (env access only) if it isn't installed. Pass
+   * `false` to always use the shim.
+   */
+  netlifyRuntime?: string | URL | false;
+}
 declare class NetlifyEnvRunner extends NodeWorkerEnvRunner {
-  constructor(opts: {
-    name: string;
-    workerEntry?: string;
-    hooks?: WorkerHooks;
-    data?: EnvRunnerData;
-  });
+  constructor(opts: NetlifyEnvRunnerOptions);
   fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
   protected _runtimeType(): string;
 }
-export { NetlifyEnvRunner };
+export { NetlifyEnvRunner, NetlifyEnvRunnerOptions };

package/dist/_chunks/netlify-runner.mjs

@@ -1,12 +1,18 @@
+import { resolveRuntimeDepSpecifier } from "./common-runtime-deps.mjs";
 import { NodeWorkerEnvRunner } from "./node-worker-runner.mjs";
 import { fileURLToPath } from "node:url";
 let _defaultEntry;
 var NetlifyEnvRunner = class extends NodeWorkerEnvRunner {
 	constructor(opts) {
 		_defaultEntry ||= fileURLToPath(import.meta.resolve("env-runner/runners/netlify/worker"));
+		const netlifyRuntime = resolveNetlifyRuntime(opts.netlifyRuntime);
 		super({
 			...opts,
-			workerEntry: opts.workerEntry || _defaultEntry
+			workerEntry: opts.workerEntry || _defaultEntry,
+			data: netlifyRuntime === void 0 ? opts.data : {
+				...opts.data,
+				netlifyRuntime
+			}
 		});
 	}
 	async fetch(input, init) {
@@ -43,4 +49,7 @@ var NetlifyEnvRunner = class extends NodeWorkerEnvRunner {
 		return "netlify";
 	}
 };
+function resolveNetlifyRuntime(runtime) {
+	return resolveRuntimeDepSpecifier(runtime, "netlifyRuntime");
+}
 export { NetlifyEnvRunner };

package/dist/_chunks/server.mjs

@@ -1,4 +1,34 @@
 import { watch } from "node:fs";
+async function createRunnerWSProxyPlugin(getRunner) {
+	const isBun = "Bun" in globalThis;
+	const isDeno = "Deno" in globalThis;
+	if (!isBun && !isDeno) return (server) => {
+		server.ready().then(() => {
+			(server.node?.server)?.on("upgrade", (req, socket, head) => {
+				getRunner()?.upgrade?.({ node: {
+					req,
+					socket,
+					head
+				} });
+			});
+		}).catch(() => {});
+	};
+	const { createWebSocketProxy } = await import("crossws");
+	const { plugin } = isBun ? await import("crossws/server/bun") : await import("crossws/server/deno");
+	const proxy = createWebSocketProxy({ target: async (peer) => {
+		await getRunner()?.waitForReady?.().catch(() => {});
+		return resolveWSProxyTarget(getRunner()?.address, peer.request.url);
+	} });
+	return plugin({ resolve: () => proxy });
+}
+function resolveWSProxyTarget(address, requestUrl) {
+	if (!address) throw new Error("env runner worker is not ready");
+	const { pathname, search } = new URL(requestUrl);
+	if (address.socketPath) return `ws+unix://${address.socketPath}:${pathname}${search}`;
+	if (!address.port) throw new Error("env runner worker is not ready");
+	const host = address.host || "127.0.0.1";
+	return `ws://${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${address.port}${pathname}${search}`;
+}
 var RunnerManager = class {
 	_runner;
 	_messageQueue = [];
@@ -9,6 +39,7 @@ var RunnerManager = class {
 	_pendingModuleReload;
 	_closeListeners = /* @__PURE__ */ new Set();
 	_readyListeners = /* @__PURE__ */ new Set();
+	_readyRejectors = /* @__PURE__ */ new Set();
 	constructor(runner) {
 		if (runner) this._attach(runner);
 	}
@@ -18,6 +49,9 @@ var RunnerManager = class {
 	get closed() {
 		return this._closed;
 	}
+	get address() {
+		return this._runner?.address;
+	}
 	async reload(runner) {
 		this._reloading = true;
 		try {
@@ -49,9 +83,17 @@ var RunnerManager = class {
 		});
 		return this._pendingModuleReload;
 	}
-	upgrade = (context) => {
-		this._runner?.upgrade?.(context);
+	upgrade = async (context) => {
+		const runner = await this._waitForRunner();
+		if (!runner?.upgrade) {
+			context.node.socket.destroy();
+			return;
+		}
+		await runner.upgrade(context);
 	};
+	wsSrvxPlugin() {
+		return createRunnerWSProxyPlugin(() => this);
+	}
 	sendMessage(message) {
 		if (!this._runner || !this._runner.ready) {
 			this._messageQueue.push(message);
@@ -67,21 +109,31 @@ var RunnerManager = class {
 		this._messageListeners.delete(listener);
 		this._runner?.offMessage(listener);
 	}
-	waitForReady(timeout = 5e3) {
+	waitForReady(timeout = 15e3) {
 		if (this.ready) return Promise.resolve();
+		if (this._closed) return Promise.reject(/* @__PURE__ */ new Error("Runner closed before becoming ready"));
 		return new Promise((resolve, reject) => {
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.offMessage(listener);
+				this._readyRejectors.delete(onClose);
+			};
 			const timer = setTimeout(() => {
-				this._messageListeners.delete(listener);
+				cleanup();
 				reject(/* @__PURE__ */ new Error("Runner did not become ready in time"));
 			}, timeout);
 			const listener = (message) => {
 				if (message?.address || this.ready) {
-					clearTimeout(timer);
-					this._messageListeners.delete(listener);
+					cleanup();
 					resolve();
 				}
 			};
-			this._messageListeners.add(listener);
+			const onClose = () => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Runner closed before becoming ready"));
+			};
+			this.onMessage(listener);
+			this._readyRejectors.add(onClose);
 		});
 	}
 	rpc(name, data, opts) {
@@ -124,6 +176,8 @@ var RunnerManager = class {
 	async close() {
 		this._closed = true;
 		this._messageQueue.length = 0;
+		for (const rejectReady of this._readyRejectors) rejectReady();
+		this._readyRejectors.clear();
 		const runner = this._runner;
 		this._detach();
 		if (runner) await runner.close();
@@ -246,6 +300,7 @@ var EnvServer = class extends RunnerManager {
 	}
 	async _createRunner() {
 		return loadRunner(this._opts.runner || "node-worker", {
+			...this._opts.runnerOptions,
 			name: this._opts.name || this._opts.entry,
 			hooks: this._opts.hooks,
 			data: {

package/dist/_chunks/types.d.mts

@@ -62,6 +62,8 @@ interface EnvRunner extends RunnerRPCHooks, AsyncDisposable {
   readonly ready: boolean;
   /** Whether the runner has been closed. */
   readonly closed: boolean;
+  /** Address the worker is listening at, once ready (`undefined` before then). */
+  readonly address?: WorkerAddress;
   /** Proxy an HTTP request to the worker. */
   fetch: FetchHandler;
   /** Proxy a WebSocket upgrade request to the worker. */

package/dist/_chunks/vercel-runner.mjs

@@ -44,7 +44,9 @@ function _checkVercelOidcToken(token = process.env.VERCEL_OIDC_TOKEN) {
 let _defaultEntry;
 const _podId = Math.random().toString(32).slice(-5);
 function generateVercelId() {
-	return `dev1::${_podId}-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}`;
+	const timestamp = Date.now().toString(36);
+	const random = randomBytes(6).toString("hex");
+	return `dev1::${_podId}-${timestamp}-${random}`;
 }
 var VercelEnvRunner = class extends NodeWorkerEnvRunner {
 	constructor(opts) {

package/dist/cli.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/cli.mjs

@@ -50,16 +50,10 @@ const server = serve({
 	port: values.port,
 	hostname: values.host,
 	gracefulShutdown: false,
-	fetch: (request) => envServer.fetch(request)
+	fetch: (request) => envServer.fetch(request),
+	plugins: [await envServer.wsSrvxPlugin()]
 });
 await server.ready();
-server.node?.server?.on("upgrade", (req, socket, head) => {
-	envServer.upgrade({ node: {
-		req,
-		socket,
-		head
-	} });
-});
 for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, async () => {
 	console.log(`\n\x1B[2mShutting down...\x1B[0m`);
 	await envServer.close();

package/dist/index.d.mts

@@ -1,10 +1,11 @@
 import { EnvRunner, FetchHandler, NodeUpgradeContext, RPCOptions, RunnerMessageListener, RunnerRPCHooks, UpgradeContext, UpgradeHandler, WorkerAddress, WorkerHooks } from "./_chunks/types.mjs";
 import { BaseEnvRunner, EnvRunnerData, VirtualModuleSource, VirtualModules } from "./_chunks/common-base-runner.mjs";
+import { RuntimeDep, resolveRuntimeDep } from "./_chunks/common-runtime-deps.mjs";
 import { DenoProcessEnvRunner } from "./_chunks/deno-process-runner.mjs";
 import { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, TransformResult } from "./_chunks/miniflare-runner.mjs";
 import { VercelEnvRunner } from "./_chunks/vercel-runner.mjs";
 import { NetlifyEnvRunner } from "./_chunks/netlify-runner.mjs";
-import { ServerOptions } from "srvx";
+import { ServerOptions, ServerPlugin } from "srvx";
 import { Hooks } from "crossws";
 /**
  * Manages an active `EnvRunner` instance, proxying all calls to it.
@@ -20,9 +21,11 @@ declare class RunnerManager implements EnvRunner, AsyncDisposable {
   private _pendingModuleReload;
   private _closeListeners;
   private _readyListeners;
+  private _readyRejectors;
   constructor(runner?: EnvRunner);
   get ready(): boolean;
   get closed(): boolean;
+  get address(): WorkerAddress | undefined;
   /**
    * Replace the active runner with a new one. Closes the previous runner.
    *
@@ -41,6 +44,14 @@ declare class RunnerManager implements EnvRunner, AsyncDisposable {
    */
   private _flushInvalidation;
   upgrade: UpgradeHandler;
+  /**
+   * Create a runtime-native WebSocket reverse-proxy plugin for the public srvx
+   * server. Attach it via `serve({ plugins: [await manager.wsSrvxPlugin()] })`:
+   * on Node it proxies the raw upgrade socket to the worker, and on Bun/Deno it
+   * bridges the WebSocket with crossws. The plugin reads the active runner
+   * lazily, so it keeps working across hot-reloads.
+   */
+  wsSrvxPlugin(): Promise<ServerPlugin>;
   sendMessage(message: unknown): void;
   onMessage(listener: RunnerMessageListener): void;
   offMessage(listener: RunnerMessageListener): void;
@@ -74,7 +85,11 @@ interface LoadRunnerOptions {
   hooks?: WorkerHooks;
   data?: EnvRunnerData;
   execArgv?: string[];
-  /** Additional runner-specific options (passed through to the runner constructor). */
+  /**
+   * Additional runner-specific options (passed through to the runner
+   * constructor) — e.g. `miniflare` (the imported `miniflare` package) for the
+   * `miniflare` runner, which this package never imports itself.
+   */
   [key: string]: unknown;
 }
 declare function loadRunner(runner: RunnerName, opts: LoadRunnerOptions): Promise<EnvRunner>;
@@ -95,6 +110,14 @@ interface EnvServerOptions {
   watch?: boolean;
   /** Additional paths to watch (directories or files). */
   watchPaths?: string[];
+  /**
+   * Extra runner-specific constructor options, spread into the runner.
+   *
+   * Runners that build on external packages take them as explicit options —
+   * e.g. `{ miniflare }` for the `miniflare` runner (env-runner never imports
+   * those packages itself).
+   */
+  runnerOptions?: Record<string, unknown>;
 }
 declare class EnvServer extends RunnerManager {
   private _opts;
@@ -146,4 +169,4 @@ interface AppEntry {
   plugins?: ServerOptions["plugins"];
   ipc?: AppEntryIPC;
 }
-export { type AppEntry, type AppEntryIPC, type AppEntryIPCContext, BaseEnvRunner, DenoProcessEnvRunner, type EnvRunnerData as DenoProcessEnvRunnerData, type EnvRunner, type EnvRunnerData, EnvServer, type EnvServerOptions, type FetchHandler, type LoadRunnerOptions, MiniflareEnvRunner, type MiniflareEnvRunnerOptions, type MiniflareExportInfo, NetlifyEnvRunner, type NodeUpgradeContext, type RPCOptions, RunnerManager, type RunnerMessageListener, type RunnerName, type RunnerRPCHooks, type TransformResult, type UpgradeContext, type UpgradeHandler, VercelEnvRunner, type VirtualModuleSource, type VirtualModules, type WorkerAddress, type WorkerHooks, loadRunner };
+export { type AppEntry, type AppEntryIPC, type AppEntryIPCContext, BaseEnvRunner, DenoProcessEnvRunner, type EnvRunnerData as DenoProcessEnvRunnerData, type EnvRunner, type EnvRunnerData, EnvServer, type EnvServerOptions, type FetchHandler, type LoadRunnerOptions, MiniflareEnvRunner, type MiniflareEnvRunnerOptions, type MiniflareExportInfo, NetlifyEnvRunner, type NodeUpgradeContext, type RPCOptions, RunnerManager, type RunnerMessageListener, type RunnerName, type RunnerRPCHooks, type RuntimeDep, type TransformResult, type UpgradeContext, type UpgradeHandler, VercelEnvRunner, type VirtualModuleSource, type VirtualModules, type WorkerAddress, type WorkerHooks, loadRunner, resolveRuntimeDep };

package/dist/index.mjs

@@ -1,7 +1,8 @@
 import { BaseEnvRunner } from "./_chunks/common-base-runner.mjs";
 import { EnvServer, RunnerManager, loadRunner } from "./_chunks/server.mjs";
+import { resolveRuntimeDep } from "./_chunks/common-runtime-deps.mjs";
 import { DenoProcessEnvRunner } from "./_chunks/deno-process-runner.mjs";
 import { MiniflareEnvRunner } from "./_chunks/miniflare-runner.mjs";
 import { VercelEnvRunner } from "./_chunks/vercel-runner.mjs";
 import { NetlifyEnvRunner } from "./_chunks/netlify-runner.mjs";
-export { BaseEnvRunner, DenoProcessEnvRunner, EnvServer, MiniflareEnvRunner, NetlifyEnvRunner, RunnerManager, VercelEnvRunner, loadRunner };
+export { BaseEnvRunner, DenoProcessEnvRunner, EnvServer, MiniflareEnvRunner, NetlifyEnvRunner, RunnerManager, VercelEnvRunner, loadRunner, resolveRuntimeDep };

package/dist/runners/bun-process/worker.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/runners/deno-process/worker.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/runners/miniflare/runner.d.mts

@@ -1,3 +1,3 @@
 import { EnvRunnerData } from "../../_chunks/common-base-runner.mjs";
-import { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, TransformResult, WranglerInlineConfig } from "../../_chunks/miniflare-runner.mjs";
-export { MiniflareEnvRunner, type EnvRunnerData as MiniflareEnvRunnerData, MiniflareEnvRunnerOptions, MiniflareExportInfo, TransformResult, type WranglerInlineConfig };
+import { MiniflareEnvRunner, MiniflareEnvRunnerOptions, MiniflareExportInfo, MiniflareModule, TransformResult, WranglerInlineConfig, WranglerModule } from "../../_chunks/miniflare-runner.mjs";
+export { MiniflareEnvRunner, type EnvRunnerData as MiniflareEnvRunnerData, MiniflareEnvRunnerOptions, MiniflareExportInfo, MiniflareModule, TransformResult, type WranglerInlineConfig, type WranglerModule };

package/dist/runners/netlify/runner.d.mts

@@ -1,3 +1,3 @@
 import { EnvRunnerData } from "../../_chunks/common-base-runner.mjs";
-import { NetlifyEnvRunner } from "../../_chunks/netlify-runner.mjs";
-export { type EnvRunnerData, NetlifyEnvRunner };
+import { NetlifyEnvRunner, NetlifyEnvRunnerOptions } from "../../_chunks/netlify-runner.mjs";
+export { type EnvRunnerData, NetlifyEnvRunner, NetlifyEnvRunnerOptions };

package/dist/runners/netlify/worker.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/runners/netlify/worker.mjs

@@ -1,41 +1,40 @@
-try {
-	const { startRuntime } = await import("@netlify/runtime");
+import { resolveRuntimeDep } from "../../_chunks/common-runtime-deps.mjs";
+import { workerData } from "node:worker_threads";
+const netlifyEnv = {
+	get: (key) => process.env[key],
+	has: (key) => key in process.env,
+	set: (key, value) => {
+		process.env[key] = value;
+	},
+	delete: (key) => {
+		delete process.env[key];
+	},
+	toObject: () => ({ ...process.env })
+};
+const runtimeSpecifier = (workerData || {}).netlifyRuntime;
+let started = false;
+if (runtimeSpecifier !== false) try {
+	const startRuntime = (await resolveRuntimeDep({
+		name: "@netlify/runtime",
+		option: "netlifyRuntime",
+		value: runtimeSpecifier,
+		expect: "startRuntime"
+	}))?.startRuntime;
+	if (!startRuntime) throw new Error("`@netlify/runtime` is not installed");
 	startRuntime({
 		deployID: "0",
 		siteID: "0",
-		env: {
-			get: (key) => process.env[key],
-			has: (key) => key in process.env,
-			set: (key, value) => {
-				process.env[key] = value;
-			},
-			delete: (key) => {
-				delete process.env[key];
-			},
-			toObject: () => ({ ...process.env })
-		},
+		env: netlifyEnv,
 		getRequestContext: () => null,
 		cache: { getCacheAPIContext: () => null }
 	});
-} catch {
-	if (!process.env.__ENV_RUNNER_NETLIFY_WARNED) {
-		process.env.__ENV_RUNNER_NETLIFY_WARNED = "1";
-		console.warn("@netlify/runtime is not installed. Install it for full Netlify runtime emulation: npx nypm i -D @netlify/runtime");
-	}
-	globalThis.Netlify = {
-		context: null,
-		env: {
-			get: (key) => process.env[key],
-			has: (key) => key in process.env,
-			set: (key, value) => {
-				process.env[key] = value;
-			},
-			delete: (key) => {
-				delete process.env[key];
-			},
-			toObject: () => ({ ...process.env })
-		}
-	};
+	started = true;
+} catch (error) {
+	if (runtimeSpecifier) console.warn(`[env-runner] failed to start the Netlify runtime from "${runtimeSpecifier}": ${error?.cause?.message || error?.message || error}`);
 }
+if (!started) globalThis.Netlify = {
+	context: null,
+	env: netlifyEnv
+};
 await import("../node-worker/worker.mjs");
 export {};

package/dist/runners/node-process/worker.d.mts

@@ -1 +1 @@
-export { };
+export {}