Edge Runtime Simulator

Common errors

• Error: The 'EdgeRuntime' class is not a constructor

  cause Attempting to use `require()` for `EdgeRuntime` in an environment where ESM is expected or configured for the package, or incorrect import syntax.
  fix Ensure 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

  cause 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.
  fix Ensure `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.

  cause Running `edge-runtime` version 4.x or higher on an incompatible Node.js version (specifically 16 or lower).
  fix Upgrade 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.

Warnings

• breaking Version 4.0.0 of `edge-runtime` dropped support for Node.js 16. Using the package with Node.js versions older than 18 will result in errors.
  Fix: Upgrade your Node.js environment to version 18 or higher (LTS recommended) or pin `edge-runtime` to a compatible major version (e.g., `^3.0.0` for Node.js 16 compatibility).
• gotcha The `EdgeRuntime` creates an isolated environment. Node.js built-in modules (e.g., `fs`, `path`) and externally installed Node.js packages are not directly accessible within the code evaluated by `runtime.evaluate()` unless explicitly passed as `initialGlobals` or polyfilled.
  Fix: For Node.js specific functionalities, perform operations outside the runtime. If certain values or functions are needed inside, pass them via the `initialGlobals` option during `EdgeRuntime` instantiation, ensuring they are serializable or compatible with the Edge environment.
• gotcha Web APIs like `fetch`, `Request`, `Response`, `URL`, `console`, etc., are available as globals within the code evaluated by the EdgeRuntime. Attempting to `import` these directly from `edge-runtime` or other libraries will lead to incorrect behavior or `undefined` errors.
  Fix: Access Web APIs as global objects directly within the code passed to `runtime.evaluate()` or through the `runtime` instance itself (e.g., `new runtime.Request()`, `await runtime.dispatchFetch()`) for external interaction.

Install

• npm install edge-runtime npm
• yarn add edge-runtime yarn
• pnpm add edge-runtime pnpm

Imports

• EdgeRuntime
  wrong:

  const { EdgeRuntime } = require('edge-runtime');

  correct:

  import { EdgeRuntime } from '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
  wrong:

  import { Request } from 'edge-runtime';

  correct:

  const request = new runtime.Request('https://example.com');

  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.

Quickstart

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);