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.
npm install next@latest
Then, create a _middleware.ts file under your /pages directory.
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:
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
index.tsx
about.tsx
teams.tsx
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
index.tsx
- /about
_middleware.ts # Will run first
about.tsx
- /teams
_middleware.ts # Will run second
teams.tsx
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.