Middleware enables you to use code over configuration. This gives you full flexibility in Next.js, because you can run code before a request is completed. Based on the user's incoming request, you can modify the response by rewriting, redirecting, adding headers, or even streaming HTML.


  1. Install the latest version of Next.js:
npm install next@latest
  1. Then, create a _middleware.ts file under your /pages directory.

  2. Finally, export a middleware function from the _middleware.ts file.

// pages/_middleware.ts

import type { NextFetchEvent, NextRequest } from 'next/server'

export function middleware(req: NextRequest, ev: NextFetchEvent) {
  return new Response('Hello, world!')

In this example, we use the standard Web API Response (MDN).


Middleware can be used for anything that shares logic for a set of pages, including:

Execution Order

If your Middleware is created in /pages/_middleware.ts, it will run on all routes within the /pages directory. The below example assumes you have about.tsx and teams.tsx routes.

- package.json
- /pages
    _middleware.ts # Will run on all routes under /pages

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

- package.json
- /pages
    - /about
      _middleware.ts # Will run first
      - /teams
        _middleware.ts # Will run second

Middleware runs directly after redirects and headers, before the first filesystem lookup. This excludes /_next files.


Middleware uses a strict runtime that supports standard Web APIs like fetch. This works out of the box using next start, as well as on Edge platforms like Vercel, which use Edge Functions.

Custom Server

When using a custom server with middleware, you must specify the hostname and port when instantiating your NextApp.

import next from 'next'
// ...
const port = process.env.PORT ? +process.env.PORT : 3000
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev, customServer: true, hostname: 'localhost', port })