env-runner

Common errors

• TypeError: Cannot read properties of undefined (reading 'onReady')

  cause Attempting to use the old callback assignment style on `RunnerManager` or `EnvServer` (e.g., `manager.onReady = ...`).
  fix Use the new event listener methods: `manager.onReady((runner, address) => { ... });` or `envServer.onReady((runner, address) => { ... });`

• Error: Cannot find module 'miniflare'

  cause Using `MiniflareEnvRunner` (or `NetlifyEnvRunner`) without having its corresponding peer dependency installed.
  fix Install the missing peer dependency: `npm install miniflare` (or `npm install @netlify/runtime`) in your project.

• Error: Module './app.ts' does not export a default 'fetch' handler.

  cause The entry module specified for the runner (e.g., `app.ts`) does not export a default object containing a `fetch` method.
  fix Ensure your application entry file has `export default { fetch(request: Request) { /* ... */ } };` at its root.

• TypeError: Class constructor NodeProcessEnvRunner cannot be invoked without 'new'

  cause Attempting to invoke a runner class constructor directly (e.g., `NodeProcessEnvRunner({...})`) instead of instantiating it with `new`.
  fix Always instantiate runner classes using the `new` keyword: `const runner = new NodeProcessEnvRunner({...});`.

Warnings

• breaking The `RunnerManager` and `EnvServer` APIs changed their event handling from direct callback properties (e.g., `onReady = () => {}`) to a multi-listener event pattern (e.g., `.onReady((runner, address) => {})`).
  Fix: Update `RunnerManager` and `EnvServer` usage to use `.on('event', listener)` or `.onEvent(listener)` methods instead of direct assignment to callback properties.
• breaking Core graceful shutdown mechanisms were removed from the package, requiring applications to implement their own shutdown logic.
  Fix: Applications must now manually handle process signals (e.g., `SIGINT`) and explicitly call `.close()` on `EnvServer` or `RunnerManager` instances to ensure proper termination.
• gotcha Specific runners, such as `MiniflareEnvRunner` or `NetlifyEnvRunner`, rely on peer dependencies (`miniflare`, `@netlify/runtime`) that must be installed separately by the consumer.
  Fix: Ensure you install the necessary peer dependencies explicitly (e.g., `npm install miniflare @netlify/runtime`) when using their respective runners.
• gotcha As a pre-1.0 package, `env-runner` may introduce frequent breaking changes between minor versions, especially in its early stages of development.
  Fix: Always consult the package's changelog before upgrading minor versions and consider pinning exact versions in production environments to prevent unexpected issues.

Install

• npm install env-runner npm
• yarn add env-runner yarn
• pnpm add env-runner pnpm

Imports

• EnvServer

  import { EnvServer } from 'env-runner'

  EnvServer provides a high-level API for running applications with watching and auto-reload.
• RunnerManager

  import { RunnerManager } from 'env-runner'

  RunnerManager is a proxy for hot-reloading, message queueing, and listener forwarding.
• NodeProcessEnvRunner
  wrong:

  import { NodeProcessEnvRunner } from 'env-runner'

  correct:

  import { NodeProcessEnvRunner } from 'env-runner/runners/node-process'

  Specific environment runners are imported from subpaths within the `env-runner/runners/` directory.

Quickstart

This quickstart demonstrates setting up `EnvServer` to run an application entry point with hot-reloading and proxy requests through a standard HTTP server. Remember to create an `app.ts` file with a default `fetch` handler.

import { serve } from "srvx";
import { EnvServer } from "env-runner";
import { fileURLToPath } from 'node:url';
import path from 'node:path';

// app.ts (your application entry point - create this file)
// export default {
//   fetch(request: Request) {
//     return new Response(`Hello from env-runner at ${new Date().toISOString()}!`);
//   },
// };

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const appEntryPath = path.join(__dirname, 'app.ts'); // Path to your app.ts entry

const envServer = new EnvServer({
  runner: "node-process", // Choose your desired runner: 'miniflare', 'bun-process', etc.
  entry: appEntryPath,
  watch: true,
  watchPaths: [path.join(__dirname, 'src')], // Example additional watch path
});

envServer.onReady((_runner, address) => {
  if (address) {
    console.log(`Worker ready on ${address.host}:${address.port}`);
  } else {
    console.log("Worker ready, but no address reported.");
  }
});

envServer.onReload(() => {
  console.log("Application reloaded!");
});

envServer.onError((error) => {
  console.error("EnvServer error:", error);
});

await envServer.start();

// Use with any HTTP server (srvx is used here as an example from the README)
const server = serve({
  fetch: (request) => envServer.fetch(request),
});

const port = process.env.PORT ? parseInt(process.env.PORT) : 3000;
server.listen({ port, host: 'localhost' });
console.log(`HTTP server listening on http://localhost:${port}`);

// Graceful shutdown
process.on('SIGINT', async () => {
  console.log('Shutting down env-runner and HTTP server...');
  await envServer.close();
  server.close();
  process.exit(0);
});