@vercel/edge Reference

The @vercel/edge package is a Node.js module that provides a set of helper functions for use in Edge Functions and Edge Middleware. These helpers are Vercel-specific, and take advantage of functionality built into the Vercel platform.

If you want to take action in your Edge Functions and Middleware based on a user's location, or IP address, we highly recommend you use these helpers. They enable you to do things like show localized content or block malicious IPs.

Read the following section to learn how to get started.

Available 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
• RequestContext: An extension to the standard Request object. Contains the waitUntil function

The following helpers are available exclusively in Edge Middleware:

• rewrite: Returns a response that rewrites the request to a different URL - Edge Middleware specific
• next - Edge Middleware specific

Add the @vercel/edge to your project with:

pnpm i @vercel/edge

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.

import { geolocation } from '@vercel/edge';
 
export const runtime = 'edge';
 
export function GET(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.

import { ipAddress } from '@vercel/edge';
 
export const runtime = 'edge';
 
export default function handler(request: Request) {
  const ip = ipAddress(request) || 'unknown';
  return new Response(`<h1>Your IP is ${ip}</h1>`, {
    headers: { 'content-type': 'text/html' },
  });
}

The RequestContext is an extension of the standard Request object that contains the waitUntil function. The following example works for Next.js apps using the pages router, and any non-Next.js framework that Vercel supports.

import type { RequestContext } from '@vercel/edge';
 
export const config = {
  runtime: 'edge',
};
 
const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
async function getAlbum() {
  const res = await fetch('https://jsonplaceholder.typicode.com/albums/1');
  await wait(10000);
  return res.json();
}
 
export default function handler(request: Request, context: RequestContext) {
  context.waitUntil(getAlbum().then((json) => console.log({ json })));
 
  return new Response(`Hello, from ${request.url} I'm an Edge Function!`);
}

The following helpers are only available in Edge Middleware.

The rewrite helper returns a response that rewrites the request to a different URL. The following example shows how to rewrite a request to a different URL:

import { rewrite } from '@vercel/edge';
export default function middleware(request: Request) {
  return rewrite(new URL('/about-2', request.url));
}

The next helper returns a Response that instructs the function to continue processing the request. The function receives a request object and returns a Response object.

The following example adds a custom header:

import { next } from '@vercel/edge';
export default function middleware() {
  return next({
    headers: { 'x-from-middleware': 'true' },
  });
}

A no-op example. This will return a 200 OK response with no further action:

import { next } from '@vercel/edge';
export default function middleware() {
  return next();
}