Registry / devops / env-runner

env-runner

JSON →
library0.1.7jsnpmunverified

env-runner is a generic environment runner for JavaScript applications, abstracting away the complexities of various runtime environments. It enables developers to run server applications across Node.js worker threads, child processes, Bun, Deno, Cloudflare Workers (via Miniflare), Vercel, Netlify, or even in-process. The package provides essential features like hot-reloading for development, WebSocket proxying, and a bidirectional messaging system between the main process and the runner environment. Currently at version 0.1.7, it is actively developed with rapid minor releases focusing on enhancements and new runner integrations, offering a unified API for deploying serverless functions or local servers across diverse JavaScript ecosystems. Its key differentiator is providing a consistent interface regardless of the underlying runtime.

npm install env-runner
INSTALL
IMPORT
SIG · ENV-RUNNER
E
env-runner
devopsjavascriptv0.1.7
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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
✓ import { NodeProcessEnvRunner } from 'env-runner/runners/node-process'
✗ import { NodeProcessEnvRunner } from 'env-runner'
Specific environment runners are imported from subpaths within the `env-runner/runners/` directory.

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); });
Debug
Known issues
breakingThe `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.
affects: >=0.1.6
breakingCore 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.
affects: >=0.1.6
gotchaSpecific 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.
affects: >=0.1.0
gotchaAs 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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'onReady')
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'
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.
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'
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({...});`.
Upgrade
Version history
0.1.7latest on npm
Audit
Dependencies
@netlify/runtimeoptionalRequired for the NetlifyEnvRunner to function correctly.
miniflareoptionalRequired for the MiniflareEnvRunner to emulate Cloudflare Workers locally.
Agent activity
4 hits · last 30 days
node
4
Resources
env-runner — npm install env-runner · libregistry