@vercel/edge Reference
Learn about the @vercel/edge package and its available helpers for use in Edge Functions and Edge Middleware.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 requestipAddress
: Returns the IP address of the request from the headersRequestContext
: An extension to the standardRequest
object. Contains thewaitUntil
function
The following helpers are available exclusively in Edge Middleware:
rewrite
: Returns a response that rewrites the request to a different URL - Edge Middleware specificnext
- 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 fromcountry
: The country that the request originated fromlatitude
: The latitude of the clientlongitude
: The longitude of the clientregion
: 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.
RequestContext
in this way is not currently supported in the Next.js app
router.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();
}
Was this helpful?