Routing Middleware API

The Routing Middleware file should be named middleware.ts and placed at the root of your project, at the same level as your package.json file. This is where Vercel will look for the Routing Middleware when processing requests.

The Routing Middleware must be a default export, with the function being named anything you like. For example, you can name it router, middleware, or any other name that makes sense for your application.

middleware.ts
export default function middleware() {}

Routing 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.

You can also use the runtime option to specify which runtime you would like to use. The default is edge.

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 Routing Middleware when it matches specific paths.

To decide which route the Routing 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.

middleware.ts
export const config = {
  matcher: '/about/:path*',
};
middleware.ts
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)
middleware.ts
export const config = {
  matcher: ['/((?!api|_next/static|favicon.ico).*)'],
};

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

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

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

middleware.ts
import { rewrite } from '@vercel/functions';
 
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 helper methods below for more information on using the @vercel/functions package.

To change the runtime from the edge default, update the runtime option as follows:

middleware.ts
export const config = {
  runtime: 'nodejs', // defaults to 'edge'
};
PropertyTypeDescription
matcherstring / string[]A string or array of strings that define the paths the Middleware should be run on
runtimestring (edge or nodejs)A string that defines the Middleware runtime and defaults to edge

The Routing 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.

ParameterDescriptionNext.js (/app) or (/pages)Other Frameworks
requestAn instance of the Request objectRequest or NextRequestRequest
contextAn extension to the standard Request objectNextFetchEventRequestContext

Routing Middleware comes with built in helpers that are based on the native FetchEvent, Response, and Request objects.

See the section on Routing Middleware helpers for more information.

middleware.ts
// 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));
}

If you're not using a framework, you must either add "type": "module" to your package.json or change your JavaScript Functions' file extensions from .js to .mjs

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.

PropertyTypeDescription
urlstringThe URL of the request
methodstringThe HTTP method of the request
headersHeadersThe headers of the request
bodyReadableStreamThe body of the request
bodyUsedbooleanWhether the body has been read
cachestringThe cache mode of the request
credentialsstringThe credentials mode of the request
destinationstringThe destination of the request
integritystringThe integrity of the request
redirectstringThe redirect mode of the request
referrerstringThe referrer of the request
referrerPolicystringThe referrer policy of the request
modestringThe mode of the request
signalAbortSignalThe signal of the request
arrayBufferfunctionReturns a promise that resolves with an ArrayBuffer
blobfunctionReturns a promise that resolves with a Blob
formDatafunctionReturns a promise that resolves with a FormData
jsonfunctionReturns a promise that resolves with a JSON object
textfunctionReturns a promise that resolves with a string
clonefunctionReturns a clone of the request

To learn more about the NextRequest object and its properties, visit the Next.js documentation.

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
  • Keep the function running for ten seconds
  • Fetch a product and log it to the console
middleware.ts
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' },
  });
}

If you're not using a framework, you must either add "type": "module" to your package.json or change your JavaScript Functions' file extensions from .js to .mjs

PropertyTypeDescription
waitUntil(promise: Promise<unknown>): voidProlongs the execution of the function until the promise passed to waitUntil is resolved

You can use Vercel-specific helper methods to access a request's geolocation, IP Address, and more when deploying Middleware on Vercel.

You can access these helper methods with the request and response objects in your middleware handler method.

These helpers are exclusive to Vercel, and will not work on other providers, even if your app is built with Next.js.

The geo helper object returns geolocation information for the incoming request. It has the following properties:

PropertyDescription
cityThe city that the request originated from
countryThe country that the request originated from
latitudeThe latitude of the client
longitudeThe longitude of the client
regionThe Edge Network region that received the request

Each property returns a string, or undefined.

middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
 
// The country to block from accessing the secret page
const BLOCKED_COUNTRY = 'SE';
 
// Trigger this middleware to run on the `/secret-page` route
export const config = {
  matcher: '/secret-page',
};
 
export default function middleware(request: NextRequest) {
  // Extract country. Default to US if not found.
  const country = (request.geo && request.geo.country) || 'US';
 
  console.log(`Visitor from ${country}`);
 
  // Specify the correct route based on the requests location
  if (country === BLOCKED_COUNTRY) {
    request.nextUrl.pathname = '/login';
  } else {
    request.nextUrl.pathname = `/secret-page`;
  }
 
  // Rewrite to URL
  return NextResponse.rewrite(request.nextUrl);
}

The ip object returns the IP address of the request from the headers, or undefined.

middleware.ts
import { ipAddress } from '@vercel/functions';
import { next } from '@vercel/functions';
 
export default function middleware(request: Request) {
  const ip = ipAddress(request);
  return next({
    headers: { 'x-your-ip-address': ip || 'unknown' },
  });
}

The RequestContext is an extension of the standard Request object, which contains the waitUntil function. The following example works in middleware for all frameworks:

middleware.ts
import type { RequestContext } from '@vercel/functions';
 
export default function handler(request: Request, context: RequestContext) {
  context.waitUntil(getAlbum().then((json) => console.log({ json })));
 
  return new Response(
    `Hello there, from ${request.url} I'm an Vercel Function!`,
  );
}
 
export const config = {
  matcher: '/',
};
 
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();
}

The NextResponse.rewrite() helper returns a response that rewrites the request to a different URL.

middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
// Trigger this middleware to run on the `/about` route
export const config = {
  matcher: '/about',
};
 
export default function middleware(request: NextRequest) {
  // Rewrite to URL
  return NextResponse.rewrite('/about-2');
}

The NextResponse.next() helper returns a Response that instructs the function to continue the middleware chain. It takes the following optional parameters:

ParametertypeDescription
headersHeaders[] or HeadersThe headers you want to set
statusnumberThe status code
statusTextstringThe status text

The following example adds a custom header, then continues the Routing Middleware chain:

middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
 
export function middleware(request: NextRequest) {
  // Clone the request headers and set a new header `x-hello-from-middleware1`
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-hello-from-middleware1', 'hello');
 
  // You can also set request headers in NextResponse.next
  const response = NextResponse.next({
    request: {
      // New request headers
      headers: requestHeaders,
    },
  });
 
  // Set a new response header `x-hello-from-middleware2`
  response.headers.set('x-hello-from-middleware2', 'hello');
  return response;
}

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

middleware.ts
import { NextResponse } from 'next/server';
export default function middleware() {
  return NextResponse.next();
}
Last updated on June 25, 2025