npm - env-runner - Versions diffs - 0.2.3 → 0.3.0 - Mend

env-runner 0.2.3 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.md +154 -19
package/dist/_chunks/common-base-runner.d.mts +52 -14
package/dist/_chunks/common-base-runner.mjs +123 -32
package/dist/_chunks/common-process-data.mjs +13 -0
package/dist/_chunks/common-worker-utils.mjs +464 -73
package/dist/_chunks/deno-process-runner.mjs +2 -6
package/dist/_chunks/lexer.mjs +2 -0
package/dist/_chunks/libs/cjs-module-lexer.mjs +6 -1
package/dist/_chunks/miniflare-runner.d.mts +21 -12
package/dist/_chunks/miniflare-runner.mjs +266 -96
package/dist/_chunks/node-worker-runner.mjs +1 -2
package/dist/_chunks/server.mjs +20 -5
package/dist/_chunks/types.d.mts +36 -0
package/dist/_chunks/virtual-loader.mjs +303 -29
package/dist/index.d.mts +17 -4
package/dist/runners/bun-process/runner.mjs +4 -8
package/dist/runners/bun-process/worker.mjs +8 -8
package/dist/runners/deno-process/worker.mjs +8 -8
package/dist/runners/node-process/runner.mjs +2 -6
package/dist/runners/node-process/worker.mjs +8 -8
package/dist/runners/node-worker/worker.mjs +6 -7
package/dist/runners/self/runner.d.mts +2 -1
package/dist/runners/self/runner.mjs +8 -0
package/package.json +11 -11
package/dist/_chunks/common-host-env.mjs +0 -11

package/README.md CHANGED Viewed

@@ -205,7 +205,8 @@ const response = await runner.fetch("/api");
 // prefer `manager.wsSrvxPlugin()` for cross-runtime proxying)
 runner.upgrade?.({ node: { req, socket, head } });
-// Wait for runner to be ready
+// Wait for runner to be ready (rejects as soon as it closes, with the close
+// reason as `error.cause`)
 await runner.waitForReady();
 // Bidirectional messaging
@@ -215,7 +216,12 @@ runner.onMessage((msg) => console.log(msg));
 // Request-response RPC
 const result = await runner.rpc<string>("transformHTML", "<html>...</html>");
-// Hot-reload entry module without restarting the worker
+// Hot-reload entry module without restarting the worker (the entry is
+// re-read under its own URL; modules it imports stay cached)
+await runner.reloadModule();
+// Add, replace or remove (`null`) virtual modules in one round trip, then reload
+await runner.updateVirtualModules({ "#routes": `export default []`, "#old": null });
 await runner.reloadModule();
 // Invalidate a virtual module (re-runs a factory source), then reload
@@ -231,7 +237,7 @@ await runner.reloadModule();
 | Runner                 | Isolation                       | IPC mechanism                      |
 | ---------------------- | ------------------------------- | ---------------------------------- |
 | `NodeWorkerEnvRunner`  | Worker thread                   | `workerData` / `parentPort`        |
-| `NodeProcessEnvRunner` | Child process (`fork`)          | `ENV_RUNNER_DATA` / `process.send` |
+| `NodeProcessEnvRunner` | Child process (`fork`)          | `process.send` IPC channel         |
 | `BunProcessEnvRunner`  | Bun or Node.js process          | `Bun.spawn` IPC or `fork()`        |
 | `DenoProcessEnvRunner` | Deno process                    | `deno run` with IPC channel        |
 | `SelfEnvRunner`        | In-process                      | In-memory channel                  |
@@ -241,7 +247,7 @@ await runner.reloadModule();
 #### Virtual Modules
-The Node.js runners (`NodeWorkerEnvRunner`, `NodeProcessEnvRunner`, and the runners built on top of them), `BunProcessEnvRunner`, `DenoProcessEnvRunner` (Deno >= 2.x), and `MiniflareEnvRunner` can serve **virtual modules** from an in-memory `specifier => source` map passed via `data.virtual`. The entry (and its dependencies) can then `import` them as if they were real files:
+The Node.js runners (`NodeWorkerEnvRunner`, `NodeProcessEnvRunner`, and the runners built on top of them), `BunProcessEnvRunner`, `DenoProcessEnvRunner` (Deno >= 2.8), and `MiniflareEnvRunner` can serve **virtual modules** from an in-memory `specifier => source` map passed via `data.virtual` (`SelfEnvRunner` cannot, and closes with an error when it is set). The entry (and its dependencies) can then `import` them as if they were real files:
 ```ts
 import { NodeWorkerEnvRunner } from "env-runner/runners/node-worker";
@@ -268,7 +274,7 @@ export default {
 };
 ```
-The **entry itself can be virtual** — set `data.entry` to one of the `data.virtual` keys to run an entry whose source lives in memory (it may import other virtual modules too):
+The **entry itself can be virtual** — set `data.entry` to one of the `data.virtual` keys (exactly as written in the map) to run an entry whose source lives in memory (it may import other virtual modules too):
 ```ts
 await using runner = new NodeWorkerEnvRunner({
@@ -284,7 +290,45 @@ await using runner = new NodeWorkerEnvRunner({
 });
 ```
-Each source may also be a **factory** `() => string | Promise<string>` instead of a literal string — useful for lazily computed or asynchronously loaded sources:
+Keys can also be **file paths**: absolute paths (including Windows `C:\...`) or `file://` URLs. Such a module behaves like a file at that path, whether or not its directory exists on disk:
+- it is matched by resolved URL, so any relative or absolute import that resolves to it is served from the map, whether the importer is a virtual module or a real file. A key equal to a real file's path therefore **overrides that file** for every importer.
+- it runs under its real `file:` URL, so `import.meta.url`, `import.meta.dirname` and `import.meta.filename` point at the key.
+- its own imports (relative files, bare packages) resolve from the key's directory.
+- as `data.entry`, it may be written either way (`/app/x.mjs` for a `file:///app/x.mjs` key, or the reverse). It is still run from the map on load and across `reloadModule()`, even when a real file exists there.
+```ts
+import { join, resolve } from "node:path";
+const dir = resolve("src/generated"); // doesn't need to exist
+await using runner = new NodeWorkerEnvRunner({
+  name: "my-app",
+  data: {
+    entry: join(dir, "entry.mjs"),
+    virtual: {
+      [join(dir, "entry.mjs")]: `import { body } from "./body.mjs";
+        export default { fetch: () => new Response(body) };`,
+      [join(dir, "body.mjs")]: `export const body = "Hello from " + import.meta.filename;`,
+      // Overrides the real `src/config.mjs` for all of its importers
+      [resolve("src/config.mjs")]: `export default { mode: "virtual" };`,
+    },
+  },
+});
+```
+Other keys (`#name`, bare names) only match an import specifier equal to the key, and relative imports inside them resolve from the working directory. Having no file, they get a runtime-specific id, shown by `import.meta.url` and stack traces: `virtual:#config` on Node.js and Deno, `file:///%23config` on Bun (`file:///env-runner-virtual:%23util.mjs` for keys with an extension), while on miniflare `import.meta.url` is undefined and stack traces show the key itself. A `?query` appended to an import is ignored for matching (`#config.json?raw` matches `#config.json`), but gives a separate module instance. Path keys are fully supported on the Node.js, Bun and Deno runners, with these exceptions:
+- On Bun (`BunProcessEnvRunner`, and the Node.js runners when the host runtime is Bun), runtime plugins only see a specifier whose last `.` is followed by a letter, typically a file extension. A key without an extension (`#config`, `/app/entry`) therefore only matches an import spelled exactly like the key: no appended `?query`, and no relative or `file://` import of an extensionless path key.
+- `MiniflareEnvRunner` supports relative imports and overrides, and treats `file://` keys and imports like their path, but `import.meta.url` is undefined.
+On both, a virtual `data.entry` must be written exactly like its key.
+Two path keys naming the same file (`/app/x.mjs` and `file:///app/x.mjs`) can't both be served, so the runner logs a warning naming both. Keep a single key per file.
+Keys match **every importer** in the worker, dependencies included, like an import map entry. A bare key such as `react` replaces that package everywhere (useful to alias or stub it), and a `#name` key also replaces a dependency's own `#name` [subpath import](https://nodejs.org/api/packages.html#subpath-imports). There is no warning for this, since overriding a package is often the point, so give your own modules distinctive names (`#app/config` rather than `#utils`).
+Each source may also be a **factory** returning a source (or a promise of one) — useful for lazily computed or asynchronously loaded sources:
 ```ts
 await using runner = new NodeWorkerEnvRunner({
@@ -299,9 +343,9 @@ await using runner = new NodeWorkerEnvRunner({
 });
 ```
-Factories are invoked once on the host (before the worker is spawned), so the worker always receives plain strings — functions can't cross the `workerData`/`JSON` boundary, and Node's synchronous load hook can't await. For the same reason, **all** factories are resolved eagerly at startup (in parallel), not lazily on first import — so keep them cheap, or use plain strings for sources that don't need computation. Maps containing only strings skip this step entirely.
+Factories are invoked once on the host (before the worker is spawned), so the worker always receives resolved sources — functions can't cross the `workerData`/`JSON` boundary, and Node's synchronous load hook can't await. For the same reason, **all** factories are resolved eagerly at startup (in parallel), not lazily on first import — so keep them cheap, or use plain sources for modules that don't need computation. Maps without factories skip this step entirely.
-To refresh a single virtual module without restarting the worker, call `invalidateModule(specifier)`: a factory-valued source is re-run on the host and the module is invalidated in the worker so its **next import evaluates fresh**. Virtual modules that import the invalidated one (directly or transitively) are invalidated along with it, so the fresh module is picked up even through intermediate virtual importers. Already-imported modules keep their instances, so pair it with `reloadModule()` to re-import the entry graph:
+To refresh a single virtual module without restarting the worker, call `invalidateModule(specifier)`: a factory-valued source is re-run on the host and the module is invalidated in the worker so its **next import evaluates fresh**. Virtual modules that import the invalidated one (directly or transitively) are invalidated along with it, so the fresh module is picked up even through intermediate virtual importers. On Node.js, Bun and Deno this follows the imports that were actually resolved, and on miniflare the import specifiers of the virtual sources, including relative ones between path keys. On Node.js and Deno it also covers **real files** on the way from the entry, such as a `./lib.mjs` importing `#config`: they are re-evaluated on the next reload too, while files that don't depend on the module stay cached. CommonJS files are never re-evaluated. On Bun and miniflare, a real file other than the entry keeps the old module. Already-imported modules keep their instances, so pair it with `reloadModule()` to re-import the entry graph:
 ```ts
 await runner.invalidateModule("#config"); // re-runs the factory, busts the module
@@ -310,9 +354,29 @@ await runner.reloadModule(); // re-imports the entry, picking up the fresh modul
 When fetching through `RunnerManager` or `EnvServer`, the reload is automatic: `invalidateModule()` marks the manager dirty and the next `fetch()` reloads the entry once before serving (concurrent fetches share the reload), so no explicit `reloadModule()` call is needed.
-The module format is derived from the specifier extension: `.ts`/`.mts` sources are served as **TypeScript** and `.json` sources as **JSON modules**; everything else is plain JavaScript ESM:
+To change the map itself while the runner is running, call `updateVirtualModules(changes)`. A source (string or factory) **adds or replaces** a key, and `null` **removes** it. All changes of one call are applied together in a single round trip to the worker:
 ```ts
+await runner.updateVirtualModules({
+  "#routes": `export default ["/", "/about"]`, // add or replace
+  [resolve("src/generated/api.mjs")]: () => generateApi(), // factories run on the host
+  "#legacy": null, // remove
+});
+await runner.reloadModule(); // or let RunnerManager/EnvServer reload on the next fetch
+```
+Changed and removed keys are invalidated like `invalidateModule()` does, together with the modules importing them, so the next `reloadModule()` sees the new map:
+- An **added** key resolves from then on, path keys included. An importer that failed to import it, or that loaded the real file it now overrides, picks it up once it is re-evaluated: the reloaded entry, virtual importers, and on Node.js and Deno also real files between them. A runner started without `data.virtual` registers its virtual modules on the first update, and real files it loaded before aren't tracked as importers.
+- A **removed** key falls through to normal resolution: the real file it overrode, or a "not found" error. On Bun, a removed key without a file extension (see the Bun notes above) fails to load instead of falling through, and on miniflare an unresolvable bare specifier gets an empty module, as usual there.
+Calls are applied one at a time in call order (a later call never loses to a slower factory of an earlier one), and `reloadModule()` waits for pending ones. A call made before the runner is ready waits for it. `invalidateModule(specifier)` is the same as updating the key with its current source. The runner keeps its own copy of the map, never changing your `data.virtual`. `RunnerManager.updateVirtualModules()` marks the manager dirty like `invalidateModule()`, and `EnvServer` also keeps the changes for the runners it creates later (`reload()`, watch mode). Changes made before the server started are only recorded, and the first runner starts with them.
+Each module has a **format**. By default it follows the key's extension, like Node.js does for files: `.cjs` is CommonJS, `.ts`/`.mts` TypeScript, `.cts` CommonJS TypeScript, `.json` JSON, `.jsx`/`.tsx` JSX and `.wasm` WebAssembly. Any other string is an ES module, and any other `Uint8Array` raw bytes. To set the format explicitly, for example on a key without an extension, pass `{ source, format }`:
+```ts
+import { readFileSync } from "node:fs";
 await using runner = new NodeWorkerEnvRunner({
   name: "my-app",
   data: {
@@ -320,31 +384,60 @@ await using runner = new NodeWorkerEnvRunner({
     virtual: {
       "#entry.ts": `
         import { getGreeting } from "#util.ts";
-        import config from "#config.json";
-        const handler: () => Response = () => new Response(getGreeting(config.name));
+        import config from "#config";
+        import legacy from "#legacy.cjs";
+        import logo from "#logo";
+        import add from "#add.wasm";
+        const { exports } = await WebAssembly.instantiate(add);
+        const handler: () => Response = () =>
+          new Response(\`\${getGreeting(config.name)} \${legacy.answer} \${logo.length} \${exports.add(1, 2)}\`);
         export default { fetch: handler };
       `,
       "#util.ts": `export function getGreeting(name: string): string {
         return \`Hello, \${name}!\`;
       }`,
-      "#config.json": JSON.stringify({ name: "virtual" }),
+      "#config": { source: JSON.stringify({ name: "virtual" }), format: "json" },
+      "#legacy.cjs": `module.exports = { answer: 42 };`,
+      "#logo": readFileSync("logo.png"), // a Uint8Array: `bytes`
+      "#add.wasm": readFileSync("add.wasm"),
     },
   },
 });
 ```
-- **TypeScript** is type-stripped by Node's native [type stripping](https://nodejs.org/api/typescript.html#type-stripping) (Node.js >= 22.18 / 23.6 — erasable syntax only) and by Bun's `ts` loader. On Deno, custom load hooks bypass its native type stripping, so sources are pre-stripped with [`module.stripTypeScriptTypes`](https://docs.deno.com/api/node/module/~/Module.stripTypeScriptTypes) (Deno >= 2.8.2); on older Deno without it, virtual `.ts`/`.mts` sources **throw at registration** — pass pre-transpiled JavaScript instead. On miniflare, sources are likewise pre-stripped with `module.stripTypeScriptTypes` on the host (workerd does not parse TypeScript).
+| Format                | Default for                | Source       | Importing it gives                                |
+| --------------------- | -------------------------- | ------------ | ------------------------------------------------- |
+| `module`              | other string sources       | string       | the ES module                                     |
+| `commonjs`            | `.cjs`                     | string       | `module.exports` as default export, named exports |
+| `module-typescript`   | `.ts`, `.mts`              | string       | the ES module, types stripped                     |
+| `commonjs-typescript` | `.cts`                     | string       | like `commonjs`, types stripped                   |
+| `json`                | `.json`                    | string       | the parsed value as default export                |
+| `jsx`, `tsx`          | `.jsx`, `.tsx`             | string       | the ES module (Bun only)                          |
+| `text`                | —                          | string       | the string as default export                      |
+| `bytes`               | other `Uint8Array` sources | `Uint8Array` | a `Uint8Array` as default export                  |
+| `wasm`                | `.wasm`                    | `Uint8Array` | a compiled `WebAssembly.Module` as default export |
+The code formats are named like Node's [load formats](https://nodejs.org/api/module.html#loadurl-context-nextload), and `text` and `bytes` like the `with { type }` import attributes proposed for them (import them without attributes, though). An unknown format, or a source that doesn't fit its format (a `Uint8Array` for `json`, a string for `wasm`, bytes that aren't valid WebAssembly), closes the runner at startup with an error naming the key, or rejects `updateVirtualModules()` before anything changes.
+- **TypeScript** is type-stripped by Node's native [type stripping](https://nodejs.org/api/typescript.html#type-stripping) (Node.js >= 22.18 / 23.6 — erasable syntax only) and by Bun's `ts` loader. On Deno, custom load hooks bypass its native type stripping, so sources are pre-stripped with [`module.stripTypeScriptTypes`](https://docs.deno.com/api/node/module/~/Module.stripTypeScriptTypes) (Deno >= 2.8.2); on older Deno without it, virtual TypeScript sources **throw at registration** — pass pre-transpiled JavaScript instead. On miniflare, sources are likewise pre-stripped with `module.stripTypeScriptTypes` on the host (workerd does not parse TypeScript).
 - **JSON** sources expose the parsed value as the default export on all runtimes. The `with { type: "json" }` import attribute is optional on Node.js and Bun; on Deno and miniflare it must be **omitted** (static imports carrying an import attribute bypass `registerHooks` resolution on Deno, and workerd rejects import attributes outright).
+- **CommonJS** is loaded natively by Node.js and workerd (miniflare). Bun and Deno only parse in-memory sources as ES modules, so there the source runs inside an ES module wrapper, as strict-mode code. Named exports are detected like Node.js does ([cjs-module-lexer](https://github.com/nodejs/cjs-module-lexer)), but re-exports (`module.exports = require("./other.cjs")`) only add named exports on Node.js. `require()` resolves packages, real files and other virtual modules, with these exceptions:
+  - On Deno, `require()` only reaches real files and packages, not virtual modules (Deno reads required files from disk), and requiring an ES module crashes Deno 2.9 while module hooks are registered (a Deno bug).
+  - On miniflare, a virtual module that is `require()`d keeps its first instance when it changes (`invalidateModule()`, updates): only `import` specifiers are rewritten. Import it instead, or restart the runner.
+  - On Node.js, after a module re-exported by CommonJS (`module.exports = require("./dep.cjs")`) changes, Node reads it as an empty, circular module (this happens with real files too after deleting them from `require.cache`). Assign it first (`const dep = require("./dep.cjs"); module.exports = dep;`).
+- **Text and bytes** can't be imported from memory natively on every runtime, so they are served as ES modules where needed. `bytes` gives each module instance its own `Uint8Array`. Bytes survive every transport, including the process runners' JSON IPC (as base64) and `updateVirtualModules()`.
+- **WebAssembly** default-exports a compiled [`WebAssembly.Module`](https://developer.mozilla.org/docs/WebAssembly/Reference/JavaScript_interface/Module) on every runtime, so instantiate it yourself with `WebAssembly.instantiate(module, imports)`. This follows workerd, which compiles `.wasm` modules ahead of time and disallows compiling Wasm at runtime. Node.js and Deno's own `.wasm` imports instantiate the module instead ([Wasm ESM integration](https://github.com/WebAssembly/esm-integration)), and Bun's give a file path, so those aren't used.
+- **JSX** is only supported on Bun, by its `jsx`/`tsx` loaders (configure the JSX runtime with `tsconfig.json` or pragma comments like `/** @jsxImportSource preact */`). Node.js, Deno and miniflare can't load JSX from memory and fail with an error naming the key: pre-transpile it to JavaScript, and pass `{ source, format: "module" }` to keep a `.jsx`/`.tsx` key.
-Virtual modules are registered inside the worker, before the entry is imported. On Node.js (>= 22.15 / 23.5) and Deno (>= 2.x) this uses [ESM customization hooks](https://nodejs.org/api/module.html#moduleregisterhooksoptions) (`module.registerHooks`); on Bun (which does not implement `registerHooks`) it uses [`Bun.plugin()`](https://bun.com/docs/runtime/plugins) virtual modules instead. The source string is treated as an ES module, and virtual specifiers (including a virtual entry) resolve across `reloadModule()`. On runtimes supporting neither mechanism, a warning is logged and registration is skipped. When the worker shuts down gracefully the registration is unregistered again (the `registerHooks` registration is deregistered; on Bun, which has no plugin-removal API, the in-memory source map is detached so fresh loads and reloads stop resolving).
+Virtual modules are registered inside the worker, before the entry is imported. On Node.js (>= 22.15 / 23.5) and Deno (>= 2.8) this uses [ESM customization hooks](https://nodejs.org/api/module.html#moduleregisterhooksoptions) (`module.registerHooks`); on Bun (which does not implement `registerHooks`) it uses a [`Bun.plugin()`](https://bun.com/docs/runtime/plugins) runtime plugin instead, also for the Node.js runners when the host runtime is Bun. Each source is served in its format, and virtual specifiers (including a virtual entry) resolve across `reloadModule()`. On runtimes supporting neither mechanism, a warning is logged and registration is skipped. When the worker shuts down gracefully the registration is unregistered again (the `registerHooks` registration is deregistered; on Bun, which has no plugin-removal API, the registration is detached so fresh loads and reloads stop resolving, and an overridden real file loads from disk again).
-On `MiniflareEnvRunner` there is no in-worker registration: the runner's module fallback service serves virtual specifiers to workerd directly (taking precedence over disk files and the `transformRequest` pipeline, so a virtual key overrides a real file with the same path). One limitation: named `exports` (Durable Objects / WorkerEntrypoints) cannot be combined with a **virtual entry** — the wrapper would need a static re-export that miniflare cannot resolve at startup — and the runner fails fast with a clear error in that case.
+On `MiniflareEnvRunner` there is no in-worker registration: the runner's module fallback service serves virtual specifiers to workerd directly (taking precedence over disk files and the `transformRequest` pipeline, so a virtual key overrides a real file with the same path). Named `exports` (Durable Objects / WorkerEntrypoints) also work with virtual entries. One limitation on miniflare v4: a **real** entry with auto-detected named exports can't import virtual modules, because miniflare's module locator reads its imports from disk at startup. Use a virtual entry, a separate `exports` module or miniflare v5 instead.
 #### Miniflare Runner
 Run your app in the Cloudflare Workers runtime using [miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare).
-`env-runner` declares no peer dependencies — install `miniflare` yourself and pass it to the runner (see [Runtime dependencies](#runtime-dependencies)):
+`env-runner` declares no peer dependencies — install `miniflare` (v4 or v5) yourself and pass it to the runner (see [Runtime dependencies](#runtime-dependencies)):
 ```bash
 npm install miniflare
@@ -431,9 +524,9 @@ await using runner = new MiniflareEnvRunner({
 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.
-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.
+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 local classes (exported by your entry or an [exports module](#exports-module)) 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.
+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`; on miniflare v5, `resourcePersistencePath`) 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.
@@ -491,7 +584,7 @@ When `transformRequest` is provided:
 - The `unsafeModuleFallbackService` calls it with the resolved file path before falling back to raw disk reads
 - Module rules for `.ts`, `.tsx`, `.jsx`, and `.mts` are added automatically
-- Static `export *` re-exports are skipped in the wrapper to avoid miniflare's ModuleLocator pre-walking the import tree
+- The wrapper never statically re-exports the entry (`export *`), to avoid miniflare's ModuleLocator pre-walking its import tree
 The callback should return `{ code: string }` for transformed modules, or `null`/`undefined` to fall back to the default raw file read.
@@ -529,6 +622,29 @@ await using runner = new MiniflareEnvRunner({
 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.
+#### Exports Module
+To load named exports from a separate module, set `exports` to its absolute path or a `data.virtual` key (a relative path resolves from the entry's directory, not the working directory). The wrapper re-exports it with `export *`, so re-exports and exported aliases work.
+In this mode nothing is auto-detected or auto-wired: configure the bindings with `wrangler` or `miniflareOptions`. The entry's own `export class` declarations are **not** re-exported either, so re-export them from the exports module if they are bound.
+```ts
+const runner = new MiniflareEnvRunner({
+  name: "app",
+  miniflare,
+  data: {
+    entry: "/path/to/server.mjs",
+    virtual: {
+      "#server-exports": 'export { Counter } from "/path/to/counter.mjs";',
+    },
+  },
+  exports: "#server-exports",
+  miniflareOptions: { durableObjects: { COUNTER: "Counter" } },
+});
+```
+In both modes, named exports are registered when the worker starts. Recreate the runner when their implementation or export list changes; `reloadModule()` only reloads the request entry.
 #### Error Capture
 By default, the runner wraps the user's `fetch` handler in a try/catch that returns structured JSON error responses with preserved stack traces:
@@ -569,6 +685,8 @@ const runner2 = new MiniflareEnvRunner({
 // Fully destroy: runner.dispose() or MiniflareEnvRunner.disposeAll()
 ```
+An instance is only reused by runners with the same virtual module sources. Once `invalidateModule()` or `updateVirtualModules()` changes them, the instance leaves the cache (runners attached to it keep using it), and later runners start a fresh one.
 #### Vercel Runner
 Simulates a Vercel deployment environment with automatic header injection (`x-vercel-deployment-url`, `x-vercel-forwarded-for`, forwarding headers) and global context.
@@ -776,6 +894,23 @@ await using runner = new NodeProcessEnvRunner({
 });
 ```
+Process runners (`NodeProcessEnvRunner`, `BunProcessEnvRunner`, `DenoProcessEnvRunner`) deliver `data` over IPC, so its size (e.g. large virtual modules) is not bound by environment variable limits. A custom process worker requests it once its message listener is attached:
+```ts
+// custom-worker.ts
+const data = await new Promise((resolve) => {
+  const onMessage = (message) => {
+    if (message?.event === "init-data") {
+      process.off("message", onMessage);
+      resolve(JSON.parse(message.data)); // `data` is sent as a JSON string
+    }
+  };
+  process.on("message", onMessage);
+  process.send({ event: "request-init-data" });
+});
+// ... start a server, then report it with `process.send({ address: { host, port } })`
+```
 ## Development
 <details>

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

@@ -1,21 +1,21 @@
-import { EnvRunner, RunnerMessageListener, WorkerAddress, WorkerHooks } from "./types.mjs";
+import { EnvRunner, ResolvedVirtualModule, RunnerMessageListener, VirtualModuleUpdates, VirtualModules, WorkerAddress, WorkerHooks } from "./types.mjs";
 import { IncomingMessage } from "node:http";
 import { Socket } from "node:net";
-/** 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 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-import": "export const foo = 1" }`. A source is a string, a
+   * `Uint8Array` or `{ source, format }` (format by extension by default), or
+   * a factory returning one, which runs on the host before spawn. Change them
+   * at runtime with `updateVirtualModules()`. Not supported by the `self`
+   * runner (it closes with an error).
    */
   virtual?: VirtualModules;
   [key: string]: unknown;
 }
 export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposable {
+  #private;
   closed: boolean;
   protected _name: string;
   protected _workerEntry: string;
@@ -25,7 +25,10 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
   protected _address?: WorkerAddress;
   protected _messageListeners: Set<(data: unknown) => void>;
   protected _pendingRequests: Set<(cause?: unknown) => void>;
+  protected _closeCause?: unknown;
   protected _virtualResolved?: Promise<void>;
+  protected _virtualUpdates: Promise<void>;
+  protected _processData?: string;
   constructor(opts: {
     name: string;
     workerEntry: string;
@@ -45,14 +48,26 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
   abstract sendMessage(message: unknown): void;
   onMessage(listener: RunnerMessageListener): void;
   offMessage(listener: RunnerMessageListener): void;
+  /** Rejects on timeout, and as soon as the runner closes (with the close cause). */
   waitForReady(timeout?: number): Promise<void>;
   rpc<T = unknown>(name: string, data?: unknown, opts?: {
     timeout?: number;
   }): Promise<T>;
+  /** Re-import the entry, after any pending `updateVirtualModules()` call. */
   reloadModule(timeout?: number): Promise<void>;
   /**
-   * Invalidate a virtual module so the next `reloadModule()` re-evaluates it.
-   * Factory sources are re-run on the host. Rejects for unknown specifiers.
+   * Set (add or replace) and remove (`null`) virtual modules in one round trip.
+   * Factory sources run on the host. Changed and removed keys, and the modules
+   * importing them, evaluate fresh on the next `reloadModule()`; a removed key
+   * falls through to normal resolution. Calls apply in order, waiting for the
+   * runner to become ready. The runner keeps its own copy of the map in sync,
+   * never changing the caller's `data.virtual`.
+   */
+  updateVirtualModules(changes: VirtualModuleUpdates, timeout?: number): Promise<void>;
+  /**
+   * Invalidate a virtual module so the next `reloadModule()` re-evaluates it:
+   * `updateVirtualModules()` with its current source, so a factory re-runs.
+   * Rejects for unknown specifiers.
    */
   invalidateModule(specifier: string, timeout?: number): Promise<void>;
   close(cause?: unknown): Promise<void>;
@@ -62,6 +77,17 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
   /** 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;
+  /**
+   * Env for a process worker. Also snapshots the runner data, which goes over
+   * IPC on request (see `common/process-data.ts`), virtual module bytes as
+   * base64; throws if not JSON-serializable.
+   */
+  protected _processEnv(): NodeJS.ProcessEnv;
+  /**
+   * Process worker messages: answer the `request-init-data` handshake with the
+   * runner data (internal, not forwarded to listeners), handle everything else.
+   */
+  protected _handleProcessMessage(message: any): void;
   /**
    * Send a message and await the matching response. Rejects on timeout, on an
    * `error` response, and as soon as the runner closes.
@@ -74,15 +100,27 @@ export declare abstract class BaseEnvRunner implements EnvRunner, AsyncDisposabl
   }): Promise<T>;
   /**
    * 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.
+   * the worker boundary; the load hook can't await), and validate every
+   * module. `undefined` when there is no factory and nothing is invalid, so
+   * subclasses can spawn synchronously.
    */
   protected _resolveVirtualData(): Promise<void> | undefined;
-  /** Re-run a factory virtual source and sync `data.virtual`; `undefined` if not a factory. */
-  protected _refreshVirtualSource(specifier: string): Promise<string | undefined>;
+  /**
+   * Queue a virtual module update. Updates apply one at a time in call order
+   * (`changes` is read when its turn comes), each after the initial factory
+   * resolution: until it settles, `_data.virtual` aliases the factory map.
+   */
+  protected _enqueueVirtualUpdate(changes: () => VirtualModuleUpdates, timeout: number): Promise<void>;
+  /**
+   * Apply resolved changes (`null` removes) to the running worker in one round
+   * trip, bytes as base64 (the message may be JSON). Overridden by runners
+   * serving virtual modules from the host.
+   */
+  protected _applyVirtualUpdates(changes: Record<string, ResolvedVirtualModule | null>, timeout: number): Promise<void>;
   /**
    * Run `init` once `data.virtual` is resolved (synchronously without factories).
-   * A failing factory closes the runner with the error as cause.
+   * A failing factory (or deferred `init`, e.g. a spawn error) closes the runner
+   * with the error as cause.
    */
   protected _initWithVirtualData(init: () => void): void;
   protected _closeSocket(): Promise<void>;