Skip to content

Edge Middleware APIs

Learn about the Edge Middleware APIs.

Edge Middleware 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 you don't have access to regular Node.js APIs such as process, path, or fs. This is because they are Node.js specific, and not available in a browser context.

Instead you have access to APIs related to networking, like fetch, request, and response, APIs that are available on the browser:

For a full list of available APIs see the Edge Runtime API documentation.

In addition to these APIs, Next.js Middleware comes with built in helpers that are based upon the native FetchEvent, Response, and Request objects.

See the next/server documentation for more information.

Note: For information and examples on writing Edge Middleware with Next.js, see the Next.js documentation.

All Middleware should be created in a single middleware.ts or middleware.js file at the root of your project. You can then export a middleware function from the file.

The following example assumes you have a route called /about in your project, and that you want to rewrite to a new route /about-2 whenever someone visits /about:

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

Middleware will be invoked for every route in your project. There are two ways to define which paths the middleware should be run on: 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, multiple paths.

export const config = {
  matcher: '/about/:path*',
};
export const config = {
  matcher: ['/about/:path*', '/dashboard/:path*'],
};
export function middleware(request) {
  if (request.Url.pathname.startsWith('/about')) {
    return rewrite(new URL('/about-2', request.url));
  }

  if (request.Url.pathname.startsWith('/dashboard')) {
    return rewrite(new URL('/dashboard/user', request.url));
  }
}

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 any native Node.js APIs. For example, you could use the path-to-regexp package to do path matches
  • You can use ES Modules and split your code into reusable files that will then be bundled together when the application is built
  • Calling require directly is not allowed. If you do use it, it might work when the import path can be statically resolved, but it is not recommended. 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.