Packages
/
edge-runtime

Edge Runtime

The edge-runtime package is the general purpose way to run Vercel Edge Functions locally, as you would in a production environment.

Installation

npm install edge-runtime --save

This package includes built-in TypeScript support.

Usage

as module

The edge-runtime package is on top of @edge-runtime/vm, extending it with EventTarget API support for handling fetch events.

import { EdgeRuntime } from 'edge-runtime'

const initialCode = `
addEventListener('fetch', event => {
  const { searchParams } = new URL(event.request.url)
  const url = searchParams.get('url')
  return event.respondWith(fetch(url))
})`

const runtime = new EdgeRuntime({ initialCode })

const response = await runtime.dispatchFetch('http://vercel.com?url=https://example.com')

// If your code logic performs asynchronous tasks, you should await them.
// https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent/waitUntil
await response.waitUntil()

// `response` is Web standard, you can use any of it's methods
console.log(response.status)

as HTTP server

You can use runServer to expose any Edge Runtime instance as regular HTTP server:

import { runServer, EdgeRuntime } from 'edge-runtime'

const runtime = new EdgeRuntime()
const server = await runServer({ runtime })

console.log(`Listening at ${server.url}`)

API

new EdgeRuntime([options])

options

Any option provided will be passed against @edge-runtime/vm.

Additionally, you can provide:

initialCode?: string

Some initial code to be evaluated as the VM for the runtime is created.

methods

It inherits from @edge-runtime/vm, plus:

VercelRuntime: string

Returns the runtime version.

runServer([options])

It will create an HTTP handler based on the given options and then immediately run a server on the provided port.

options

Any option provided will be passed against .createHandler, plus:

port? :number

The port to start the server. If none is provided it will use a random available port.

methods

url: string

The server URLs.

waitUntil: () => Promise<any[]>

Waits for all current effects returning their result.

close: () => Promise<void>

Waits for all the current effects and closes the server.

If you call .close, it will implicitly call .waitUntil.

createHandler([options])

Creates a Node.js HTTP handler.

options

runtime: EdgeRuntime

The Edge Runtime instance to be used that should be previously declared.

logger?: Logger

The logger to be used. If none is provided there will be no logs.

interface LoggerOptions {
  color?: keyof Colors
  withHeader?: boolean
  withBreakline?: boolean
}

interface Logger {
  (message: string, opts?: LoggerOptions): void
  debug(message: string, opts?: LoggerOptions): void
  error(message: string, opts?: LoggerOptions): void
  info(message: string, opts?: LoggerOptions): void
  quotes(str: string): string
}