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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EdgeRuntime
✓ import { EdgeRuntime } from 'edge-runtime';
✗ const { EdgeRuntime } = require('edge-runtime');
The primary class for creating a simulated Edge environment. ESM is the preferred and often only reliable import method in modern Node.js versions compatible with this library.
EdgeRuntimeOptions
✓ import type { EdgeRuntimeOptions } from 'edge-runtime';
Type definition for configuring the EdgeRuntime instance, useful for TypeScript projects.
Request
✓ const request = new runtime.Request('https://example.com');
✗ import { Request } from 'edge-runtime';
Web APIs like `Request`, `Response`, `URL`, and `fetch` are exposed as globals within the `EdgeRuntime` instance and should not be imported directly from the package. Access them via the runtime instance or within evaluated code.
Demonstrates initializing an EdgeRuntime instance, injecting global variables, evaluating Edge Function code, and simulating a fetch event to receive a response.
import { EdgeRuntime } from 'edge-runtime';
async function runEdgeFunctionSimulation() {
// Instantiate the Edge Runtime, optionally providing initial globals
const runtime = new EdgeRuntime({
initialGlobals: {
// Simulate environment variables or other global objects
MY_SECRET_KEY: process.env.MY_SECRET_KEY ?? 'default-secret',
SOME_CONFIG: { foo: 'bar' }
}
});
// Define your Edge Function code as a string
const edgeFunctionCode = `
addEventListener('fetch', event => {
const url = new URL(event.request.url);
if (url.pathname === '/api/greet') {
event.respondWith(new Response('Hello from the Edge!', {
status: 200,
headers: { 'content-type': 'text/plain' }
}));
} else if (url.pathname === '/api/config') {
event.respondWith(new Response(JSON.stringify(SOME_CONFIG), {
status: 200,
headers: { 'content-type': 'application/json' }
}));
} else if (url.pathname === '/api/secret') {
event.respondWith(new Response(MY_SECRET_KEY, {
status: 200,
headers: { 'content-type': 'text/plain' }
}));
} else {
event.respondWith(new Response('Not Found', { status: 404 }));
}
});
`;
// Evaluate the Edge Function code within the simulated runtime
runtime.evaluate(edgeFunctionCode);
// Simulate an incoming fetch request
const request1 = new runtime.Request('https://example.com/api/greet');
const response1 = await runtime.dispatchFetch(request1);
console.log('Response 1 Status:', response1.status);
console.log('Response 1 Body:', await response1.text());
const request2 = new runtime.Request('https://example.com/api/config');
const response2 = await runtime.dispatchFetch(request2);
console.log('Response 2 Status:', response2.status);
console.log('Response 2 Body:', await response2.json());
const request3 = new runtime.Request('https://example.com/api/secret');
const response3 = await runtime.dispatchFetch(request3);
console.log('Response 3 Status:', response3.status);
console.log('Response 3 Body:', await response3.text());
}
runEdgeFunctionSimulation().catch(console.error);
edge-runtime --version
Errors
Common errors & fixes
Error: The 'EdgeRuntime' class is not a constructor
Attempting to use `require()` for `EdgeRuntime` in an environment where ESM is expected or configured for the package, or incorrect import syntax.
fixEnsure you are using `import { EdgeRuntime } from 'edge-runtime';` for ESM contexts. If stuck on CommonJS, you might need to configure your build system or Node.js environment for ESM compatibility or target an older major version of `edge-runtime` if one exists with CJS support. ReferenceError: fetch is not defined
Trying to use the `fetch` global outside of the `EdgeRuntime` context in a standard Node.js environment, or within evaluated code before the runtime is properly initialized.
fixEnsure `fetch` calls are made within the JavaScript code string passed to `runtime.evaluate()`, or use `await runtime.dispatchFetch(request)` to simulate an external fetch event against the runtime.
Node.js version 16 is not supported by edge-runtime@4.x. Please upgrade to Node.js >=18.
Running `edge-runtime` version 4.x or higher on an incompatible Node.js version (specifically 16 or lower).
fixUpgrade your Node.js installation to version 18 or later. Alternatively, if Node.js 16 support is critical, you must use `edge-runtime` version `^3.0.0` or earlier.
Audit
Dependencies
@edge-runtime/ponyfillrequiredProvides Web API polyfills and ponyfills for the runtime environment.
@edge-runtime/formatrequiredInternal utility for code formatting within the runtime.
@edge-runtime/vmrequiredCore VM implementation for executing code in an isolated context.
@edge-runtime/primitivesrequiredFundamental Web API primitives required by the runtime.