env-runner 0.1.16 → 0.2.1

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/node-worker-runner.mjs

@@ -1,4 +1,5 @@
 import { BaseEnvRunner } from "./common-base-runner.mjs";
+import { hostEnv } from "./common-host-env.mjs";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import { Worker } from "node:worker_threads";
@@ -37,7 +38,7 @@ var NodeWorkerEnvRunner = class extends BaseEnvRunner {
 			return;
 		}
 		const worker = new Worker(this._workerEntry, {
-			env: { ...process.env },
+			env: hostEnv(),
 			workerData: {
 				name: this._name,
 				...this._data

package/dist/_chunks/server.mjs

@@ -300,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/cli.d.mts

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

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 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";
@@ -84,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>;
@@ -105,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;
@@ -156,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/runner.mjs

@@ -1,4 +1,5 @@
 import { BaseEnvRunner } from "../../_chunks/common-base-runner.mjs";
+import { hostEnv } from "../../_chunks/common-host-env.mjs";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import { execSync, spawn } from "node:child_process";
@@ -56,11 +57,10 @@ var BunProcessEnvRunner = class extends BaseEnvRunner {
 			this.close(`process entry not found in "${this._workerEntry}".`);
 			return;
 		}
-		const env = {
-			...process.env,
+		const env = hostEnv({
 			ENV_RUNNER_NAME: this._name,
 			ENV_RUNNER_DATA: JSON.stringify(this._data || {})
-		};
+		});
 		if (_isBun) this.#initBunProcess(execArgv, env);
 		else this.#initNodeProcess(execArgv, env);
 	}

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/runner.mjs

@@ -1,4 +1,5 @@
 import { BaseEnvRunner } from "../../_chunks/common-base-runner.mjs";
+import { hostEnv } from "../../_chunks/common-host-env.mjs";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import { fork } from "node:child_process";
@@ -35,11 +36,10 @@ var NodeProcessEnvRunner = class extends BaseEnvRunner {
 			return;
 		}
 		const child = fork(this._workerEntry, [], {
-			env: {
-				...process.env,
+			env: hostEnv({
 				ENV_RUNNER_NAME: this._name,
 				ENV_RUNNER_DATA: JSON.stringify(this._data || {})
-			},
+			}),
 			stdio: [
 				"pipe",
 				"pipe",

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

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

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

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

package/dist/runners/vercel/queue-dev.d.mts

@@ -1,9 +1,64 @@
-import { MessageHandler, RetryHandler } from "@vercel/queue";
+import { RuntimeDep } from "../../_chunks/common-runtime-deps.mjs";
+/** Metadata passed alongside each delivered message (`MessageMetadata`). */
+interface VercelQueueMessageMetadata {
+  messageId: string;
+  deliveryCount: number;
+  createdAt: Date;
+  expiresAt: Date;
+  topicName: string;
+  consumerGroup: string;
+  /** Vercel region the client is targeting. */
+  region: string;
+}
+/** Instruction returned by a retry handler when the message handler throws. */
+type VercelQueueRetryDirective = {
+  afterSeconds: number;
+} | {
+  acknowledge: true;
+};
+/** Function invoked with each delivered message (`MessageHandler`). */
+type VercelQueueMessageHandler<T = unknown> = (message: T, metadata: VercelQueueMessageMetadata) => Promise<void> | void;
+/** Called when the message handler throws (`RetryHandler`). */
+type VercelQueueRetryHandler = (error: unknown, metadata: VercelQueueMessageMetadata) => VercelQueueRetryDirective | void | undefined;
+/**
+ * The `@vercel/queue` package, as imported by the consumer
+ * (`import * as queue from "@vercel/queue"`). Structurally typed so the real
+ * module namespace is assignable without env-runner depending on the package.
+ */
+interface VercelQueueSdk {
+  QueueClient: new (options?: any) => any;
+  registerDevConsumer?: (options: {
+    topic: string;
+    client: any;
+    handler: VercelQueueMessageHandler;
+    consumerGroup?: string;
+    visibilityTimeoutSeconds?: number;
+    retry?: VercelQueueRetryHandler;
+  }) => () => void;
+  [key: string]: unknown;
+}
 interface VercelQueueDevConsumer {
+  /**
+   * The `@vercel/queue` package: the imported module, or a specifier for it.
+   *
+   * ```ts
+   * import * as sdk from "@vercel/queue";
+   * await registerVercelQueueConsumer({ sdk, topic: "orders", handler });
+   *
+   * // or, equivalently
+   * await registerVercelQueueConsumer({ sdk: "@vercel/queue", topic, handler });
+   * ```
+   *
+   * Passing it explicitly is preferred (`@vercel/queue` is not a dependency of
+   * `env-runner`). Bare specifiers resolve from the current working directory.
+   * When omitted, `@vercel/queue` is imported optionally and registration
+   * becomes a no-op if the package isn't installed.
+   */
+  sdk?: RuntimeDep<VercelQueueSdk>;
   /** Topic name. Wildcard patterns (e.g. `"user-*"`) are supported. */
   topic: string;
   /** Function invoked with each delivered message. */
-  handler: MessageHandler;
+  handler: VercelQueueMessageHandler;
   /**
    * Logical consumer identifier. Re-registering with the same group on the same
    * topic replaces the previous handler (HMR-safe). Use distinct groups to fan
@@ -27,18 +82,18 @@ interface VercelQueueDevConsumer {
    * `{ afterSeconds }` to reschedule, `{ acknowledge: true }` to drop, or
    * `undefined` to let the error propagate.
    */
-  retry?: RetryHandler;
+  retry?: VercelQueueRetryHandler;
 }
 /**
  * Bind a handler to a topic. Resolves to an unregister function.
  *
- * The first call across the worker process lazily loads `@vercel/queue` and
- * constructs a shared `QueueClient`. Re-registering with the same topic
+ * A shared `QueueClient` is constructed from `sdk` on first use and reused for
+ * later registrations with the same SDK. Re-registering with the same topic
  * replaces the handler (HMR-safe; the SDK keys consumers by `consumerGroup`,
  * so calling unregister on a replaced registration is a no-op).
  *
- * If `@vercel/queue` is not installed or does not expose `registerDevConsumer`,
+ * If no SDK is available, or it does not expose `registerDevConsumer`,
  * resolves to a no-op unregister and logs a one-time warning.
  */
 declare function registerVercelQueueConsumer(consumer: VercelQueueDevConsumer): Promise<() => void>;
-export { VercelQueueDevConsumer, registerVercelQueueConsumer };
+export { VercelQueueDevConsumer, VercelQueueMessageHandler, VercelQueueMessageMetadata, VercelQueueRetryDirective, VercelQueueRetryHandler, VercelQueueSdk, registerVercelQueueConsumer };

package/dist/runners/vercel/queue-dev.mjs

@@ -1,10 +1,31 @@
+import { resolveRuntimeDep } from "../../_chunks/common-runtime-deps.mjs";
 const DEFAULT_CONSUMER_GROUP = "env-runner-vercel-dev";
-let sdkPromise;
-let client;
+const _clients = /* @__PURE__ */ new WeakMap();
+const _warned = /* @__PURE__ */ new WeakSet();
+let _warnedMissing = false;
+let _importedSdk;
 const noop = () => {};
 async function registerVercelQueueConsumer(consumer) {
-	const sdk = await ensureSdk();
-	if (!sdk || !client) return noop;
+	const sdk = await resolveSdk(consumer.sdk);
+	if (!sdk) {
+		if (!_warnedMissing) {
+			_warnedMissing = true;
+			console.warn("[env-runner:vercel-queue] `@vercel/queue` is not installed and no `sdk` was passed. Local queue delivery is disabled.");
+		}
+		return noop;
+	}
+	if (typeof sdk.registerDevConsumer !== "function") {
+		if (!_warned.has(sdk)) {
+			_warned.add(sdk);
+			console.warn("[env-runner:vercel-queue] The `@vercel/queue` SDK in use does not export `registerDevConsumer`. Upgrade @vercel/queue@^0.2.0 to enable local queue delivery.");
+		}
+		return noop;
+	}
+	let client = _clients.get(sdk);
+	if (!client) {
+		client = new sdk.QueueClient();
+		_clients.set(sdk, client);
+	}
 	return sdk.registerDevConsumer({
 		topic: consumer.topic,
 		client,
@@ -14,23 +35,16 @@ async function registerVercelQueueConsumer(consumer) {
 		retry: consumer.retry ?? (consumer.retryAfterSeconds === void 0 ? void 0 : () => ({ afterSeconds: consumer.retryAfterSeconds }))
 	});
 }
-function ensureSdk() {
-	if (sdkPromise) return sdkPromise;
-	sdkPromise = (async () => {
-		let mod;
-		try {
-			mod = await import("@vercel/queue");
-		} catch {
-			console.warn("[env-runner:vercel-queue] `@vercel/queue` is not installed. Local queue delivery is disabled.");
-			return null;
-		}
-		if (typeof mod.registerDevConsumer !== "function") {
-			console.warn("[env-runner:vercel-queue] Installed `@vercel/queue` does not export `registerDevConsumer`. Upgrade @vercel/queue@^0.2.0 to enable local queue delivery.");
-			return null;
-		}
-		client = new mod.QueueClient();
-		return mod;
-	})();
-	return sdkPromise;
+function resolveSdk(value) {
+	if (value !== void 0) return resolveRuntimeDep({
+		name: "@vercel/queue",
+		option: "sdk",
+		value
+	});
+	_importedSdk ??= resolveRuntimeDep({
+		name: "@vercel/queue",
+		option: "sdk"
+	});
+	return _importedSdk;
 }
 export { registerVercelQueueConsumer };

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

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