Skip to content

Edge Functions API

Learn about the Edge Runtime and available APIs when working with Edge Functions

Edge Functions are available in Beta on all plans

Edge Functions use the Edge Runtime, a runtime that is built on top of V8. The Edge Runtime exposes a subset of Web Standard APIs such as FetchEvent, Response, and Request.

These native Web API objects are extended to give you more control over how you manipulate and configure a response, based on the incoming requests.

The Edge Runtime can execute V8 code, but doesn't have access to native Node.js APIs such as process, path, or fs.

Instead, you have access to Web APIs like fetch, request, and response.

You can use process.env to access Environment Variables.

If you are using Edge Functions outside of Next.js, you can use the @vercel/edge package, which exports the following helpers for use in Edge Functions:

  • geolocation: Returns the location information for the incoming request
  • ipAddress: Returns the IP address of the request from the headers

Add the @vercel/edge to your project with:


npm i @vercel/edge

Installing @vercel/edge using the npm command.

The geolocation helper returns the location information for the incoming request. The function receives a request object and returns the following properties:

  • city: The city that the request originated from
  • country: The country that the request originated from
  • latitude: The latitude of the client
  • longitude: The longitude of the client
  • region: The Vercel Edge Network region that received the request

Each property returns a string, or undefined.

index.ts
import { geolocation } from '@vercel/edge';

export const config = {
  runtime: 'experimental-edge',
};

export default function (request: Request) {
  const { city } = geolocation(request);
  // You can also get the city using dot notation on the function
  // const city = geolocation(request).city;

  return new Response(`<h1>Your location is ${city}</h1>`, {
    headers: { 'content-type': 'text/html' },
  });
}

The ipAddress helper returns the IP address of the request from the headers. The function receives a request object, and the returned value is a string with the IP address, or undefined.

index.ts
import { ipAddress } from '@vercel/edge';

export const config = {
  runtime: 'experimental-edge',
};

export default function (request: Request) {
  const ip = ipAddress(request) || 'unknown';

  return new Response(`<h1>Your IP is ${ip}</h1>`, {
    headers: { 'content-type': 'text/html' },
  });
}

Edge Functions are invoked in the region nearest to the user unless otherwise specified. You can specify which region each Edge Function should run in by adding the regions key to the config object. Set the value to the ID of your preferred region, as shown below:

pages/api/hello.ts
import { NextRequest, NextResponse } from 'next/server';

export default (req: NextRequest) => {
  return NextResponse.json({
    name: `Hello, from ${req.url} I'm now an Edge Function!`,
  });
};

export const config = {
  runtime: 'experimental-edge', // this is a pre-requisite
  regions: ['iad1'], // only execute this function on iad1
};

Read our docs on Edge Network regions to learn more about the benefits of configuring regions for your Edge Functions. Check out our list of Edge regions to find the appropriate region ID.

The Edge Runtime has some restrictions including:

  • Native Node.js APIs are not supported. For example, you can't read or write to the filesystem
  • node_modules can be used, as long as they implement ES Modules and do not use native Node.js APIs
  • Calling require directly is not allowed. Use ES Modules instead

The following JavaScript language features are disabled, and will not work:

  • eval: Evaluates JavaScript code represented as a string
  • new Function(evalString): Creates a new function with the code provided as an argument

See Edge Middleware Limitations for more information on these limitations.