Warning: Edge Functions are currently in Beta . The API might change as we look to continually make improvements.

Middleware is an advanced feature of Next.js that enables you to execute code before a request is completed. Based on the request, you can modify the response. Middleware can be used for anything that shares logic between pages. Depending on the incoming request, you can execute custom logic, rewrite, redirect, add headers and more, before returning a response.

Middleware is created by using a middleware function that lives inside a _middleware file in your project's pages directory. Its API is based upon the native FetchEvent, Response, and Request objects.

Middleware usage

To start using Middleware in your Next.js project, begin by upgrading to the latest Next.js version. Once you create a _middleware file in your project's pages directory, Vercel will automatically deploy it as an Edge Function. For an example of creating Edge Functions with Middleware, see the Quickstart or refer to the examples repository.

The middleware function takes two parameters, request and event. The request parameter is an extension of the native Request interface and has added methods and properties that include accessing cookies, getting geo location from an IP Address and user-agent info. You can import its type definition with NextRequest.

In addition you can import the NextResponse API, which extends the native Response interface and lets you redirect, rewrite, create a json response, access cookies, set a cookie, and clear cookies.

Middleware running order

If you place the middleware file at the root of your pages folder (pages/_middleware.ts), it will be called for every single request. Note this also includes static assets.

If you do not have any sub-directories, the middleware will run on all routes within the /pages directory and public files like /favicon.ico. The below example assumes you have about.ts and teams.ts routes.

If you place it under a certain path within the pages folder (pages/dashboard/_middleware.ts) then your middleware will be invoked only for those pages that live under /dashboard*.

If you do have sub-directories with nested routes, the Middleware will run in a top-down fashion. For example, if you have created /pages/about/_middleware.ts and /pages/about/team/_middleware.ts, the Middleware will run first on /pages/about, and then /pages/about/team. The below example shows how this works with a nested routing structure.

Because defining a middleware function can increase latency we encourage you to use a specific path unless your use case requires activating the Middleware for every single request. Note that you can have more than one Middleware in your application.

Runtime

Once the Middleware is deployed, it will run within a V8 Runtime with a subset of APIs. In development, the code will run in a sandbox environment that emulates the production runtime.

There are some restrictions to writing Middleware for Edge Functions. These are documented in the Middleware API guide.