Edge Middleware API Reference

Edge Middleware runs on the Edge Runtime, a runtime built on top of the V8 JavaScript engine. The Edge Runtime provides a subset of Web APIs for you to use when creating Middleware. This lightweight API layer is built to be performant and execute code with minimal latency. When writing Middleware, you can use any of the supported APIs from the Edge Runtime.

To add Middleware to your app, you need to create a middleware.ts or middleware.js file at the same level as your app or pages directory (even if you're using a src directory):

The Middleware function must be a default export as shown below:

export default function customName() {}

Middleware will be invoked for every route in your project. If you only want it to be run on specific paths, you can define those either with a custom matcher config or with conditional statements.

While the config option is the preferred method, as it does not get invoked on every request, you can also use conditional statements to only run the Middleware when it matches specific paths.

To decide which route the Middleware should be run on, you can use a custom matcher config to filter on specific paths. The matcher property can be used to define either a single path, or using an array syntax for multiple paths.

export const config = {
  matcher: '/about/:path*',
};

export const config = {
  matcher: ['/about/:path*', '/dashboard/:path*'],
};

The matcher config has full regex support for cases such as negative lookaheads or character matching.

To match all request paths except for the ones starting with:

• api (API routes)
• _next/static (static files)
• favicon.ico (favicon file)

export const config = {
  matcher: ['/((?!api|_next/static|favicon.ico).*)'],
};

To match /blog/123 but not /blog/abc:

export const config = {
  matcher: ['/blog/:slug(\\d{1,})'],
};

For help on writing your own regex path matcher, review Path to regexp.

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

See the @vercel/edge documentation for more information on using the @vercel/edge package.

The Edge Middleware signature is made up of two parameters: request and context. The request parameter is an instance of the Request object, and the context parameter is an object containing the waitUntil method. Both parameters are optional.

// config with custom matcher
export const config = {
  matcher: '/about/:path*',
};
 
export default function middleware(request: Request) {
  return Response.redirect(new URL('/about-2', request.url));
}

The Request object represents an HTTP request. It is a wrapper around the Fetch API Request object. When using TypeScript, you do not need to import the Request object, as it is already available in the global scope.

The waitUntil() method is from the ExtendableEvent interface. It accepts a Promise as an argument, which will keep the function running until the Promise resolves.

It can be used to keep the function running after a response has been sent. This is useful when you have an async task that you want to keep running after returning a response.

The example below will send a response immediately, but will keep the function running for ten seconds, fetch a product and log it to the console.

import type { NextFetchEvent } from 'next/server';
 
export const config = {
  matcher: '/',
};
 
const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
async function getProduct() {
  const res = await fetch('https://api.vercel.app/products/1');
  await wait(10000);
  return res.json();
}
 
export default function middleware(request: Request, context: NextFetchEvent) {
  context.waitUntil(getProduct().then((json) => console.log({ json })));
 
  return new Response(JSON.stringify({ hello: 'world' }), {
    status: 200,
    headers: { 'content-type': 'application/json' },
  });
}