env-runner 0.2.2 → 0.2.3

package/README.md

@@ -373,7 +373,9 @@ Passing `miniflare` explicitly is preferred — the version you install is then
 
 The entry uses the same `AppEntry` format as the other runners. Requests are handled like srvx's Cloudflare adapter (`srvx/cloudflare`): the entry's `plugins`, `middleware` and `error` handler are applied, and the request carries `request.runtime` (`{ name: "cloudflare", cloudflare: { env, context } }`), `request.ip` (from `cf-connecting-ip`) and `request.waitUntil()`. For Workers-style entries, `fetch` still receives `(request, env, ctx)`. env-runner's internal bindings are never exposed on `env`. Listener-level srvx options (`maxRequestBodySize`, `trustProxy`, `node`/`bun`/`deno`, ...) do not apply to miniflare.
 
-When you don't set a `compatibilityDate` (via `miniflareOptions` or a wrangler config), it defaults to the date supported by the installed `workerd` binary rather than today's date — the binary always lags the calendar slightly, and pinning a future date makes `workerd` refuse to start.
+When you don't set a compatibility date, it defaults to the date supported by the installed `workerd` binary rather than today's date — the binary always lags the calendar slightly, and pinning a future date makes `workerd` refuse to start. Set the runner's `compatibilityDate` option to pin one, or to `"latest"` to use the installed `workerd`'s supported date explicitly (no need to import `miniflare` for `supportedCompatibilityDate`). Precedence: `miniflareOptions.compatibilityDate` > `compatibilityDate` > the wrangler config's `compatibility_date` > the supported date. Whatever the source, a date newer than the installed `workerd` supports falls back to the supported date with a warning (like `wrangler dev`).
+
+The runner enables the `nodejs_compat` compatibility flag by default. Set `no_nodejs_compat` (in the wrangler config's `compatibility_flags` or in `miniflareOptions.compatibilityFlags`) to opt out; the generated wrapper then avoids Node.js built-ins. If the two sources disagree, `miniflareOptions` wins.
 
 #### Wrangler Config
 
@@ -386,12 +388,15 @@ await using runner = new MiniflareEnvRunner({
   miniflare,
   name: "my-worker",
   data: { entry: "./worker.ts" },
-  wrangler: true, // auto-discover wrangler.{json,jsonc,toml} next to the entry, then cwd
+  wrangler: true, // auto-discover wrangler.{json,jsonc,toml} (see below)
   // wrangler: "./config/wrangler.toml", // or an explicit path
   // wranglerEnv: "production",          // select a `[env.production]` block
+  // compatibilityDate: "latest",        // override the config's compatibility_date
 });
 ```
 
+Auto-discovery searches parent directories: when the entry file is inside the current working directory, it walks up from the entry's directory to the filesystem root (so a config at a monorepo root is found for an entry in `apps/web/src/`); when the entry lives elsewhere (e.g. a framework entry hoisted under `node_modules/.pnpm`), only the entry's own directory is checked before walking up from the cwd, so the cwd's config is never shadowed by one above the entry. The nearest directory wins; within one directory `wrangler.json` is preferred over `wrangler.jsonc`, then `wrangler.toml` (unlike `wrangler`, which looks for each filename all the way up before trying the next). A config found in a parent directory is logged once.
+
 `wranglerEnv` selects a named Wrangler environment (`--env`). When omitted, it defaults to the `CLOUDFLARE_ENV` environment variable, so `CLOUDFLARE_ENV=production` selects the `production` env without passing the option.
 
 You can also pass an **inline** config object (raw `wrangler.json` shape) instead of (or in addition to) a file — handy for programmatic setups:
@@ -410,9 +415,27 @@ await using runner = new MiniflareEnvRunner({
 });
 ```
 
-When an inline config is passed, a `wrangler.{json,jsonc,toml}` file is still auto-discovered (next to the entry, then cwd) and loaded, and the inline config is **merged on top of it** — inline values win per key, binding records (e.g. `vars`) merge, and `compatibilityFlags` are unioned. This lets you keep a committed `wrangler` file and override a few fields programmatically.
+When an inline config is passed, a `wrangler.{json,jsonc,toml}` file is still auto-discovered (as above) and loaded, and the inline config is **merged on top of it** — inline values win per key, binding records (e.g. `vars`) merge, and `compatibilityFlags` are unioned. This lets you keep a committed `wrangler` file and override a few fields programmatically. If the inline config doesn't define the selected `wranglerEnv`, its top level is used as-is (the file's env still applies), and a config that fails to load only warns without discarding the other one.
+
+Set `wranglerConfigPath` to load a specific config file instead of auto-discovering one — with `wrangler: true` or an inline config (which still merges on top), and without changing the working directory:
+
+```ts
+await using runner = new MiniflareEnvRunner({
+  miniflare,
+  name: "my-worker",
+  data: { entry: "./.nitro/dev/index.mjs" },
+  wrangler: { vars: { GREETING: "hello" } },
+  wranglerConfigPath: "./wrangler.jsonc", // relative to cwd
+});
+```
+
+A missing `wranglerConfigPath` file warns (an inline config is still applied). When `wrangler` is itself a string path, that path wins and `wranglerConfigPath` is ignored.
 
-Pass the [`wrangler`](https://www.npmjs.com/package/wrangler) package as `wranglerModule` — the imported module or a specifier — for full fidelity: TOML, `env` inheritance, `.dev.vars`, and every binding type.
+The runner hosts a single fetch-only worker, so config entries it can't run are **dropped**: `assets`, `services`, `queues.consumers`, `workflows`, `tail_consumers`/`streaming_tail_consumers`, and Durable Object bindings to another script (`script_name`). Durable Object bindings to classes exported by your entry are kept — including bindings whose `script_name` is the worker's own `name` (the inline config's `name` when set, else the file's; with `wranglerEnv` suffixed `-<env>` unless the env section sets a `name`, e.g. `my-worker-staging`), which are local in `wrangler dev` too — and merged with [auto-detected exports](#auto-detected-exports). Pass any of the dropped options via `miniflareOptions` to opt back in.
+
+Whenever `wrangler` is enabled (`true`, a path, or an inline config), local state (KV, D1, R2, Durable Objects, ...) persists under `<dir>/.wrangler/state/v3` — the same place `wrangler dev` uses, so both share data. `<dir>` is the directory of the loaded config file, else of the requested config path (`wrangler` string or `wranglerConfigPath`, even if the file is missing), else the current working directory (e.g. inline-only configs, or `wrangler: true` with no file found). Set `miniflareOptions.defaultPersistRoot` (or any `*Persist` option, e.g. `kvPersist: false`) to opt out.
+
+Pass the [`wrangler`](https://www.npmjs.com/package/wrangler) package as `wranglerModule` — the imported module or a specifier — for full fidelity: TOML, config validation, and every binding type.
 
 ```ts
 import * as miniflare from "miniflare";
@@ -427,7 +450,26 @@ await using runner = new MiniflareEnvRunner({
 });
 ```
 
-Without `wranglerModule`, `wrangler` is imported optionally; if that fails too, a built-in minimal reader handles plain JSON files and inline objects (common fields only) and JSONC/TOML files are skipped with a warning (they need `wrangler` to parse). Pass `wranglerModule: false` to always use the minimal reader. Values you pass in `miniflareOptions` always take precedence over config-derived ones — binding records (e.g. `bindings`) merge per key, and `compatibilityFlags` are merged.
+With the `wrangler` package, wrangler's own config warnings (e.g. unexpected/misspelled keys, or a `wranglerEnv` the config doesn't define) are printed for a config file — once per file version and env, so hot reloads don't repeat them. Inline configs are validated without printing wrangler's warnings (load errors still warn). As in `wrangler dev`, unexpected keys also trigger wrangler's npm update check (cached for a day), which may print a "newer version of Wrangler available" hint.
+
+Set `wranglerEnvFiles` to load local dev vars/secrets from custom `.env` files, like `getPlatformProxy({ envFiles })`:
+
+```ts
+await using runner = new MiniflareEnvRunner({
+  miniflare,
+  wranglerModule: wrangler,
+  name: "my-worker",
+  data: { entry: "./worker.ts" },
+  wrangler: true,
+  wranglerEnvFiles: [".env", ".env.development"], // relative to the config file's dir
+});
+```
+
+Paths resolve against the loaded config file's directory (else the current working directory) and later files override earlier ones. When set (non-empty), `.dev.vars` is not read; when unset, wrangler's defaults apply (`.dev.vars[.<env>]`, else `.env*`); an empty array reads `.dev.vars` but no `.env*` files. Both the `wrangler` package and the built-in minimal reader honor it.
+
+Without `wranglerModule`, `wrangler` is imported optionally; if that fails too, a built-in minimal reader handles JSON/JSONC files and inline objects (TOML files are skipped with a warning). It follows wrangler's semantics for `env` selection (bindings and `vars` are not inherited into a named env), local ids (`preview_id` / `preview_bucket_name` / `preview_database_id` first, so state is shared with `wrangler dev`), SQLite-backed Durable Objects (`migrations[].new_sqlite_classes`) and dev vars (`.dev.vars[.<env>]`, `.env*`, `secrets.required`), but only maps common bindings (`vars`, KV, R2, D1, Durable Objects, queue producers); other bindings (e.g. `hyperdrive`, `ai`, `ratelimits`) are ignored with a warning. Pass `wranglerModule: false` to always use the minimal reader. Values you pass in `miniflareOptions` always take precedence over config-derived ones — binding records (e.g. `bindings`) merge per key, and `compatibilityFlags` are merged.
+
+Config options a single dev worker can't run — `services`, `assets`, `queues.consumers`, `workflows`, `tail_consumers`/`streaming_tail_consumers`, and `durable_objects` bindings with a `script_name` naming another worker — are ignored with one warning listing them (e.g. `services (MY_SERVICE)`); pass the equivalent Miniflare options via `miniflareOptions` to opt in.
 
 #### Module Transform Pipeline
 
@@ -465,9 +507,9 @@ export class Counter {
 
 export default {
   async fetch(request, env) {
-    // env.Counter is auto-wired — no manual config needed
-    const id = env.Counter.idFromName("test");
-    const stub = env.Counter.get(id);
+    // env.COUNTER is auto-wired — no manual config needed
+    const id = env.COUNTER.idFromName("test");
+    const stub = env.COUNTER.get(id);
     return stub.fetch(request);
   },
 };
@@ -485,7 +527,7 @@ await using runner = new MiniflareEnvRunner({
 });
 ```
 
-Set `exports: false` to disable auto-detection entirely.
+Auto-wired bindings are merged with Durable Object bindings from `miniflareOptions` and a wrangler config: exports whose class is already bound (or whose binding name is taken) are skipped. Set `exports: false` to disable auto-detection entirely.
 
 #### Error Capture
 

package/dist/_chunks/common-base-runner.d.mts

@@ -1,33 +1,16 @@
 import { EnvRunner, RunnerMessageListener, WorkerAddress, WorkerHooks } from "./types.mjs";
 import { IncomingMessage } from "node:http";
 import { Socket } from "node:net";
-/**
- * Source for a virtual module: either a literal ES module string or a factory
- * that returns one (sync or async).
- *
- * Factories are evaluated **once on the host side** before the worker is spawned
- * (functions can't cross the `workerData`/`JSON` boundary, and Node's synchronous
- * load hook can't await), so the worker always receives plain strings. See
- * {@link resolveVirtualModules}.
- */
+/** Factories run once on the host, before the worker spawns. */
 export type VirtualModuleSource = string | (() => string | Promise<string>);
 /** Virtual modules as a `specifier => source` map. */
 export type VirtualModules = Record<string, VirtualModuleSource>;
 export interface EnvRunnerData {
   name?: string;
   /**
-   * Virtual modules as a `specifier => source` map.
-   *
-   * Registered as Node.js ESM customization hooks in the worker so the entry
-   * (and its dependencies) can `import` them, e.g.
-   * `{ "#virtual-import": "export const foo = 1" }`.
-   *
-   * Each source may be a string or a factory `() => string | Promise<string>`.
-   * Factories are evaluated once on the host before the worker is spawned (so the
-   * worker always receives plain strings).
-   *
-   * Supported by the `node-worker`, `node-process`, `bun-process`,
-   * `deno-process`, `vercel`, `netlify`, and `miniflare` runners.
+   * Virtual modules importable from the entry, e.g.
+   * `{ "#virtual-import": "export const foo = 1" }`. Factory sources run once
+   * on the host before spawn. Not supported by the `self` runner.
    */
   virtual?: VirtualModules;
   [key: string]: unknown;
@@ -69,25 +52,19 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
   reloadModule(timeout?: number): Promise<void>;
   /**
    * Invalidate a virtual module so the next `reloadModule()` re-evaluates it.
-   * A factory-valued `data.virtual` source is re-run on the host and the fresh
-   * source is shipped to the worker along with the invalidation. Rejects when
-   * the specifier is not a registered virtual module.
+   * Factory sources are re-run on the host. Rejects for unknown specifiers.
    */
   invalidateModule(specifier: string, timeout?: number): Promise<void>;
   close(cause?: unknown): Promise<void>;
   [Symbol.asyncDispose](): Promise<void>;
-  /**
-   * Resolve a relative fetch input (e.g. `"/path"`) against a placeholder
-   * `http://localhost` origin so it parses as a full URL. The origin is a
-   * placeholder — requests are dispatched to the worker address regardless.
-   */
+  /** Briefly back off (~3s total) while the worker is still starting. */
+  protected _waitForAddress(): Promise<void>;
+  /** Placeholder origin for relative inputs; requests go to the worker address regardless. */
   protected _resolveFetchInput(input: string | URL | Request): string | URL | Request;
   protected _handleMessage(message: any): void;
   /**
-   * Send a message and await a matching response message. Shared by `rpc()`,
-   * `reloadModule()`, and `invalidateModule()`. Rejects on timeout, on a
-   * response carrying an `error`, and promptly when the runner closes mid-wait
-   * (instead of letting callers wait out the timeout on a dead worker).
+   * Send a message and await the matching response. Rejects on timeout, on an
+   * `error` response, and as soon as the runner closes.
    */
   protected _request<T = unknown>(message: unknown, opts: {
     match: (msg: any) => boolean;
@@ -96,24 +73,16 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
     send?: (message: unknown) => void;
   }): Promise<T>;
   /**
-   * Resolve any factory-valued `data.virtual` sources to strings before the
-   * worker is spawned. Returns a pending promise only when there is async work
-   * to do (a factory is present); otherwise returns `undefined` so subclasses can
-   * keep their synchronous spawn path. Factories must be resolved here because
-   * functions can't cross the worker boundary and the load hook can't await.
+   * Resolve factory `data.virtual` sources before spawn (functions can't cross
+   * the worker boundary; the load hook can't await). `undefined` when there is
+   * no factory, so subclasses can spawn synchronously.
    */
   protected _resolveVirtualData(): Promise<void> | undefined;
-  /**
-   * Re-run a factory-valued virtual source on the host and sync the resolved
-   * `data.virtual` map. Returns the fresh source, or `undefined` when the
-   * source is a plain string or unknown (nothing to re-evaluate).
-   */
+  /** Re-run a factory virtual source and sync `data.virtual`; `undefined` if not a factory. */
   protected _refreshVirtualSource(specifier: string): Promise<string | undefined>;
   /**
-   * Run a subclass spawn callback after `data.virtual` is resolved.
-   * Synchronous when no factory-valued source is present; otherwise defers
-   * `init` until factories resolve. A throwing/rejecting factory closes the
-   * runner with the error as cause instead of leaving an unhandled rejection.
+   * Run `init` once `data.virtual` is resolved (synchronously without factories).
+   * A failing factory closes the runner with the error as cause.
    */
   protected _initWithVirtualData(init: () => void): void;
   protected _closeSocket(): Promise<void>;

package/dist/_chunks/common-base-runner.mjs

@@ -27,7 +27,7 @@ var BaseEnvRunner = class {
 		return this._address;
 	}
 	async fetch(input, init) {
-		for (let i = 0; i < 5 && !this._address && !this.closed; i++) await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i)));
+		await this._waitForAddress();
 		if (!this._address) return new Response(`${this._runtimeType()} env runner is unavailable`, { status: 503 });
 		return proxyFetch(this._address, this._resolveFetchInput(input), init);
 	}
@@ -118,6 +118,9 @@ var BaseEnvRunner = class {
 		const status = this.closed ? "closed" : this.ready ? "ready" : "pending";
 		return `${this.constructor.name}#${this._name}(${status})`;
 	}
+	async _waitForAddress() {
+		for (let i = 0; i < 5 && !this._address && !this.closed; i++) await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i)));
+	}
 	_resolveFetchInput(input) {
 		if (typeof input === "string" && !URL.canParse(input)) return new URL(input, "http://localhost");
 		return input;

package/dist/_chunks/common-runtime-deps.d.mts

@@ -1,18 +1,7 @@
 /**
- * A runtime dependency the application owns, not `env-runner`.
- *
- * Every runner option that names an external package accepts the same three
- * shapes, so the choice is about ergonomics rather than per-runner API:
- *
- * - the **imported module** (`import * as miniflare from "miniflare"`) — the
- *   version installed by the app is the version that runs
- * - a **module specifier** (`"miniflare"`, `import.meta.resolve("miniflare")`,
- *   or a `URL`) — resolved from {@link ResolveRuntimeDepOptions.from} (cwd by
- *   default), so a bare specifier resolves against the app rather than against
- *   `env-runner`'s own `node_modules`
- * - `false` — opt out of the package entirely
- *
- * Omitting the option falls back to an optional `import()` of the package.
+ * An app-owned package: the imported module, a specifier (resolved from the
+ * app, not `env-runner`), or `false` to opt out. Omitted falls back to an
+ * optional `import()`.
  */
 export type RuntimeDep<T> = T | string | URL | false;
 interface ResolveRuntimeDepOptions<T> {
@@ -22,29 +11,17 @@ interface ResolveRuntimeDepOptions<T> {
   option: string;
   /** Value as passed by the caller. */
   value?: RuntimeDep<T>;
-  /**
-   * Named export the resolved module must expose. A module that lacks it is
-   * treated as the wrong package (throws for an explicit value).
-   */
+  /** Named export identifying the package (a mismatch throws for an explicit value). */
   expect?: string;
   /** Directory bare specifiers resolve from. @default process.cwd() */
   from?: string;
-  /**
-   * Throw when the package cannot be resolved at all. Otherwise an
-   * unavailable optional package resolves to `undefined` and the caller
-   * degrades (minimal reader, shim, no-op).
-   */
+  /** Throw when unresolvable instead of resolving `undefined` (callers degrade). */
   required?: boolean;
   /** Extra sentence appended to the "not installed" error when `required`. */
   hint?: string;
 }
 /**
- * Resolve a {@link RuntimeDep} to an imported module.
- *
- * Resolution order: `false` → `undefined`; an imported module → validated and
- * returned as-is; a specifier → imported (errors propagate, since an explicit
- * specifier that cannot load is a mistake worth surfacing); omitted → optional
- * `import(name)`, which yields `undefined` when the package isn't installed
- * unless {@link ResolveRuntimeDepOptions.required} is set.
+ * Resolve a {@link RuntimeDep} to a module. An explicit specifier that fails to
+ * import throws; an omitted one resolves `undefined` unless `required`.
  */
 export declare function resolveRuntimeDep<T>(opts: ResolveRuntimeDepOptions<T>): Promise<T | undefined>;

package/dist/_chunks/deno-process-runner.mjs

@@ -26,7 +26,7 @@ var DenoProcessEnvRunner = class extends BaseEnvRunner {
 	}
 	async _closeRuntime() {
 		if (!this.#process) return;
-		this.#process.removeAllListeners?.();
+		this.#process.removeAllListeners();
 		try {
 			this.#process.kill();
 		} catch {}
@@ -37,10 +37,6 @@ var DenoProcessEnvRunner = class extends BaseEnvRunner {
 			this.close(`process entry not found in "${this._workerEntry}".`);
 			return;
 		}
-		const env = hostEnv({
-			ENV_RUNNER_NAME: this._name,
-			ENV_RUNNER_DATA: JSON.stringify(this._data || {})
-		});
 		const child = spawn("deno", [
 			"run",
 			"-A",
@@ -49,28 +45,20 @@ var DenoProcessEnvRunner = class extends BaseEnvRunner {
 			...execArgv || [],
 			this._workerEntry
 		], {
-			env,
+			env: hostEnv({
+				ENV_RUNNER_NAME: this._name,
+				ENV_RUNNER_DATA: JSON.stringify(this._data || {})
+			}),
 			stdio: [
 				"pipe",
 				"pipe",
-				"pipe"
-			]
-		});
-		const exited = new Promise((resolve) => {
-			child.once("exit", (code) => resolve(code ?? 1));
+				"pipe",
+				"ipc"
+			],
+			serialization: "json"
 		});
-		const handle = {
-			pid: child.pid,
-			kill: () => child.kill(),
-			send: (message) => {
-				child.stdin.write(JSON.stringify(message) + "\n");
-			},
-			exited,
-			_exitCode: void 0,
-			removeAllListeners: () => child.removeAllListeners()
-		};
 		child.once("exit", (code) => {
-			handle._exitCode = code;
+			child._exitCode = code;
 			this.close(`process exited with code ${code}`);
 		});
 		child.on("error", (error) => {
@@ -79,22 +67,12 @@ var DenoProcessEnvRunner = class extends BaseEnvRunner {
 				this.close(error);
 			}
 		});
-		let buffer = "";
-		child.stdout.on("data", (chunk) => {
-			buffer += chunk.toString();
-			let newlineIdx;
-			while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
-				const line = buffer.slice(0, newlineIdx);
-				buffer = buffer.slice(newlineIdx + 1);
-				if (line.startsWith("{")) try {
-					this._handleMessage(JSON.parse(line));
-					continue;
-				} catch {}
-				process.stdout.write(line + "\n");
-			}
+		child.on("message", (message) => {
+			this._handleMessage(message);
 		});
+		child.stdout?.pipe(process.stdout);
 		child.stderr?.pipe(process.stderr);
-		this.#process = handle;
+		this.#process = child;
 	}
 };
 export { DenoProcessEnvRunner };

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

@@ -3,14 +3,7 @@ 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.
- */
+/** The `wrangler` package namespace, as imported by the app. */
 export interface WranglerModule {
   unstable_readConfig?: (...args: any[]) => any;
   unstable_getMiniflareWorkerOptions?: (...args: any[]) => any;
@@ -26,20 +19,10 @@ export interface TransformResult {
 export 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.
- */
+/** The `miniflare` package namespace, as imported by the app. */
 export interface MiniflareModule {
   Miniflare: new (options: any) => any;
-  /**
-   * Newest compatibility date supported by the installed `workerd` binary,
-   * clamped to today. Used as the default `compatibilityDate`.
-   */
+  /** Newest date the installed `workerd` supports, clamped to today. */
   supportedCompatibilityDate?: string;
   [key: string]: unknown;
 }
@@ -48,98 +31,68 @@ export interface MiniflareEnvRunnerOptions {
   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.
+   * The `miniflare` package (`import * as miniflare from "miniflare"`) or a
+   * specifier resolved from cwd. Omitted: imported optionally.
    */
   miniflare?: RuntimeDep<MiniflareModule>;
   /** Options passed directly to the Miniflare constructor. */
   miniflareOptions?: Record<string, unknown>;
   /**
-   * Optional module transform callback. When provided, the module fallback
-   * service calls this instead of reading raw files from disk.
-   *
-   * This enables integration with Vite's transform pipeline — pass
-   * `environment.transformRequest` to get TS/JSX/etc. compiled on the fly.
-   *
-   * @param id - Absolute file path of the module to transform
-   * @returns Transformed code, or null/undefined to fall back to raw disk read
+   * `"latest"` uses the installed workerd's newest date. Precedence:
+   * `miniflareOptions` > this > wrangler config > newest supported. Dates newer
+   * than workerd supports fall back with a warning (workerd refuses them).
    */
-  transformRequest?: (id: string) => Promise<TransformResult | null | undefined>;
+  compatibilityDate?: "latest" | (string & {});
   /**
-   * Declare named exports (Durable Objects, WorkerEntrypoints) to auto-wire
-   * bindings and generate re-exports in the wrapper module.
-   *
-   * When set to `true`, `export class` declarations are auto-detected from
-   * the entry file. When set to a record, the listed exports are used
-   * (merged with auto-detected ones). Disabled by default.
+   * Transform modules served by the fallback service (e.g. Vite's
+   * `environment.transformRequest`). `id` is an absolute path; return nullish to
+   * read from disk.
    */
-  exports?: Record<string, MiniflareExportInfo> | boolean;
+  transformRequest?: (id: string) => Promise<TransformResult | null | undefined>;
   /**
-   * When `true`, the Miniflare instance is cached and reused across runner
-   * swaps (e.g. via `RunnerManager.reload()`). `close()` tears down IPC but
-   * keeps Miniflare alive. Call `dispose()` to fully destroy it.
+   * Named exports (Durable Objects, WorkerEntrypoints) to bind and re-export.
+   * `true` detects `export class`; a record merges with detected ones.
    */
+  exports?: Record<string, MiniflareExportInfo> | boolean;
+  /** Reuse the Miniflare instance across runner swaps; only `dispose()` destroys it. */
   persistent?: boolean;
   /** Wrap the user's `fetch` in a try/catch that returns structured JSON error responses. Default: `true`. */
   captureErrors?: boolean;
-  /**
-   * Export conditions for bare-specifier module resolution in the module
-   * fallback service. Ensures packages with conditional exports (e.g.
-   * `"workerd"`) resolve to the correct entry instead of the Node.js one.
-   *
-   * Defaults to `["workerd", "worker"]`.
-   */
+  /** Export conditions for the fallback service (default `["workerd", "worker"]`). */
   exportConditions?: string[];
   /**
-   * Load a Cloudflare `wrangler` config to populate Miniflare options
-   * (compatibility date/flags and bindings: `vars`, KV, R2, D1, Durable
-   * Objects, queues).
+   * Load a wrangler config into Miniflare options (compat date/flags, bindings).
    *
-   * - `true` — auto-discover `wrangler.{json,jsonc,toml}` next to the entry
-   *   file, then in the current working directory.
-   * - `string` — explicit path to a wrangler config file.
-   * - `object` — an inline raw (snake_case) wrangler config, as you would
-   *   write in `wrangler.json` (no file needed). A config file is still
-   *   auto-discovered (next to the entry, then cwd) and the inline config is
-   *   merged on top of it (inline wins per key, binding records merge,
-   *   `compatibilityFlags` are unioned).
+   * - `true` — auto-discover `wrangler.{json,jsonc,toml}` near the entry or cwd
+   * - `string` — config file path
+   * - `object` — inline raw config merged over the file config (inline wins per
+   *   key, binding records merge, flags union); its top level is used when it
+   *   lacks the selected env
    *
-   * 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) — 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.
+   * Options a single dev worker can't run (`assets`, services, queue consumers,
+   * workflows, tails, other-script Durable Objects) are dropped with a warning.
+   * `defaultPersistRoot` defaults to `.wrangler/state/v3` next to the config
+   * (else cwd), shared with `wrangler dev`. The `wrangler` package gives full
+   * fidelity (and may run its npm update check); without it only plain JSON is
+   * read. `miniflareOptions` always win.
    */
   wrangler?: boolean | string | WranglerInlineConfig;
   /**
-   * Wrangler environment (`--env`) to select when loading the config.
-   * Defaults to the `CLOUDFLARE_ENV` environment variable.
+   * Config file instead of auto-discovery when `wrangler` is `true` or inline
+   * (resolved from cwd). Ignored when `wrangler` is a path.
    */
+  wranglerConfigPath?: string;
+  /** Wrangler `--env` to select (default: `CLOUDFLARE_ENV`). */
   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.
+   * `.env` files for dev vars (like `getPlatformProxy({ envFiles })`), resolved
+   * from the config dir; later files win. Non-empty skips `.dev.vars`; `[]`
+   * reads only `.dev.vars`. Requires the `wrangler` package.
+   */
+  wranglerEnvFiles?: string[];
+  /**
+   * The `wrangler` package for full-fidelity config parsing. Omitted: imported
+   * optionally. `false`: always use the minimal JSON reader.
    */
   wranglerModule?: RuntimeDep<WranglerModule>;
 }
@@ -152,24 +105,11 @@ export declare class MiniflareEnvRunner extends BaseEnvRunner {
   dispose(): Promise<void>;
   fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
   sendMessage(message: unknown): void;
-  /**
-   * Hot-reload the user entry module without recreating the Miniflare instance.
-   *
-   * Sends `reload-module` event over the WebSocket. The worker wrapper uses
-   * `unsafeEvalBinding` to re-import the entry with a cache-busting query string
-   * and responds with `module-reloaded` when done.
-   */
+  /** Hot-reload the entry without recreating the Miniflare instance. */
   reloadModule(timeout?: number): Promise<void>;
   /**
-   * Invalidate a virtual module so the next `reloadModule()` re-evaluates it.
-   *
-   * Host-side only (no worker round-trip): the module fallback service serves
-   * virtual sources from a live map, so re-running a factory source and
-   * bumping the per-specifier versions — the module plus its transitive
-   * virtual importers — is enough. Import specifiers in re-served module code
-   * are rewritten to the versioned form, giving workerd fresh module
-   * identities (it caches by name). A `persistent` instance is evicted from
-   * the cache, since its served sources no longer match the cache key.
+   * Host-side only: the fallback service serves a live map, so bumping versions
+   * (see {@link rewriteVirtualImports}) is enough.
    */
   invalidateModule(specifier: string, _timeout?: number): Promise<void>;
   protected _hasRuntime(): boolean;