{"id":17429,"library":"edge-runtime","title":"Edge Runtime Simulator","description":"edge-runtime is a JavaScript/TypeScript library, currently at version 4.0.1, developed by Vercel. It provides a robust, spec-compliant environment for simulating Vercel Edge Functions or any Web-standard compliant JavaScript code within Node.js or a CLI. This enables local development, testing, and debugging of Edge Functions without requiring actual deployment, significantly streamlining the development workflow. The library aims to faithfully replicate the Edge Function environment, offering Web APIs like `fetch`, `Request`, `Response`, and `URL` as globals within its isolated context. It maintains an active release cadence, with major versions typically aligning with Node.js LTS updates or substantial API enhancements, as demonstrated by the v4.0.0 release which raised the minimum Node.js version requirement. Its core differentiation lies in providing a high-fidelity simulation of the Vercel Edge context.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/vercel/edge-runtime","tags":["javascript","edge","edge-runtime","functions","runtime","standard","web","typescript"],"install":[{"cmd":"npm install edge-runtime","lang":"bash","label":"npm"},{"cmd":"yarn add edge-runtime","lang":"bash","label":"yarn"},{"cmd":"pnpm add edge-runtime","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides Web API polyfills and ponyfills for the runtime environment.","package":"@edge-runtime/ponyfill","optional":false},{"reason":"Internal utility for code formatting within the runtime.","package":"@edge-runtime/format","optional":false},{"reason":"Core VM implementation for executing code in an isolated context.","package":"@edge-runtime/vm","optional":false},{"reason":"Fundamental Web API primitives required by the runtime.","package":"@edge-runtime/primitives","optional":false}],"imports":[{"note":"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.","wrong":"const { EdgeRuntime } = require('edge-runtime');","symbol":"EdgeRuntime","correct":"import { EdgeRuntime } from 'edge-runtime';"},{"note":"Type definition for configuring the EdgeRuntime instance, useful for TypeScript projects.","symbol":"EdgeRuntimeOptions","correct":"import type { EdgeRuntimeOptions } from 'edge-runtime';"},{"note":"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.","wrong":"import { Request } from 'edge-runtime';","symbol":"Request","correct":"const request = new runtime.Request('https://example.com');"}],"quickstart":{"code":"import { EdgeRuntime } from 'edge-runtime';\n\nasync function runEdgeFunctionSimulation() {\n  // Instantiate the Edge Runtime, optionally providing initial globals\n  const runtime = new EdgeRuntime({\n    initialGlobals: {\n      // Simulate environment variables or other global objects\n      MY_SECRET_KEY: process.env.MY_SECRET_KEY ?? 'default-secret',\n      SOME_CONFIG: { foo: 'bar' }\n    }\n  });\n\n  // Define your Edge Function code as a string\n  const edgeFunctionCode = `\n    addEventListener('fetch', event => {\n      const url = new URL(event.request.url);\n\n      if (url.pathname === '/api/greet') {\n        event.respondWith(new Response('Hello from the Edge!', {\n          status: 200,\n          headers: { 'content-type': 'text/plain' }\n        }));\n      } else if (url.pathname === '/api/config') {\n        event.respondWith(new Response(JSON.stringify(SOME_CONFIG), {\n          status: 200,\n          headers: { 'content-type': 'application/json' }\n        }));\n      } else if (url.pathname === '/api/secret') {\n        event.respondWith(new Response(MY_SECRET_KEY, {\n          status: 200,\n          headers: { 'content-type': 'text/plain' }\n        }));\n      } else {\n        event.respondWith(new Response('Not Found', { status: 404 }));\n      }\n    });\n  `;\n\n  // Evaluate the Edge Function code within the simulated runtime\n  runtime.evaluate(edgeFunctionCode);\n\n  // Simulate an incoming fetch request\n  const request1 = new runtime.Request('https://example.com/api/greet');\n  const response1 = await runtime.dispatchFetch(request1);\n  console.log('Response 1 Status:', response1.status);\n  console.log('Response 1 Body:', await response1.text());\n\n  const request2 = new runtime.Request('https://example.com/api/config');\n  const response2 = await runtime.dispatchFetch(request2);\n  console.log('Response 2 Status:', response2.status);\n  console.log('Response 2 Body:', await response2.json());\n\n  const request3 = new runtime.Request('https://example.com/api/secret');\n  const response3 = await runtime.dispatchFetch(request3);\n  console.log('Response 3 Status:', response3.status);\n  console.log('Response 3 Body:', await response3.text());\n}\n\nrunEdgeFunctionSimulation().catch(console.error);","lang":"typescript","description":"Demonstrates initializing an EdgeRuntime instance, injecting global variables, evaluating Edge Function code, and simulating a fetch event to receive a response."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` for `EdgeRuntime` in an environment where ESM is expected or configured for the package, or incorrect import syntax.","error":"Error: The 'EdgeRuntime' class is not a constructor"},{"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.","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.","error":"ReferenceError: fetch is not defined"},{"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.","cause":"Running `edge-runtime` version 4.x or higher on an incompatible Node.js version (specifically 16 or lower).","error":"Node.js version 16 is not supported by edge-runtime@4.x. Please upgrade to Node.js >=18."}],"ecosystem":"npm","meta_description":null}