135 lines
5.8 KiB
Text
135 lines
5.8 KiB
Text
---
|
|
title: middleware.js
|
|
description: API reference for the middleware.js file.
|
|
related:
|
|
title: Learn more about Middleware
|
|
links:
|
|
- app/building-your-application/routing/middleware
|
|
---
|
|
|
|
The `middleware.js|ts` file is used to write [Middleware](/docs/app/building-your-application/routing/middleware) and run code on the server before a request is completed. Then, based on the incoming request, you can modify the response by rewriting, redirecting, modifying the request or response headers, or responding directly.
|
|
|
|
Middleware executes before routes are rendered. It's particularly useful for implementing custom server-side logic like authentication, logging, or handling redirects.
|
|
|
|
Use the file `middleware.ts` (or .js) in the root of your project to define Middleware. For example, at the same level as `app` or `pages`, or inside `src` if applicable.
|
|
|
|
```tsx filename="middleware.ts" switcher
|
|
import { NextResponse, NextRequest } from 'next/server'
|
|
|
|
// This function can be marked `async` if using `await` inside
|
|
export function middleware(request: NextRequest) {
|
|
return NextResponse.redirect(new URL('/home', request.url))
|
|
}
|
|
|
|
export const config = {
|
|
matcher: '/about/:path*',
|
|
}
|
|
```
|
|
|
|
```js filename="middleware.js" switcher
|
|
import { NextResponse } from 'next/server'
|
|
|
|
// This function can be marked `async` if using `await` inside
|
|
export function middleware(request) {
|
|
return NextResponse.redirect(new URL('/home', request.url))
|
|
}
|
|
|
|
export const config = {
|
|
matcher: '/about/:path*',
|
|
}
|
|
```
|
|
|
|
## Exports
|
|
|
|
### Middleware function
|
|
|
|
The file must export a single function, either as a default export or named `middleware`. Note that multiple middleware from the same file are not supported.
|
|
|
|
```js filename="middleware.js"
|
|
// Example of default export
|
|
export default function middleware(request) {
|
|
// Middleware logic
|
|
}
|
|
```
|
|
|
|
### Config object (optional)
|
|
|
|
Optionally, a config object can be exported alongside the Middleware function. This object includes the [matcher](#matcher) to specify paths where the Middleware applies.
|
|
|
|
#### Matcher
|
|
|
|
The `matcher` option allows you to target specific paths for the Middleware to run on. You can specify these paths in several ways:
|
|
|
|
- For a single path: Directly use a string to define the path, like `'/about'`.
|
|
- For multiple paths: Use an array to list multiple paths, such as `matcher: ['/about', '/contact']`, which applies the Middleware to both `/about` and `/contact`.
|
|
|
|
Additionally, `matcher` supports complex path specifications through regular expressions, such as `matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)']`, enabling precise control over which paths to include or exclude.
|
|
|
|
The `matcher` option also accepts an array of objects with the following keys:
|
|
|
|
- `source`: The path or pattern used to match the request paths. It can be a string for direct path matching or a pattern for more complex matching.
|
|
- `regexp` (optional): A regular expression string that fine-tunes the matching based on the source. It provides additional control over which paths are included or excluded.
|
|
- `locale` (optional): A boolean that, when set to `false`, ignores locale-based routing in path matching.
|
|
- `has` (optional): Specifies conditions based on the presence of specific request elements such as headers, query parameters, or cookies.
|
|
- `missing` (optional): Focuses on conditions where certain request elements are absent, like missing headers or cookies.
|
|
|
|
```js filename="middleware.js"
|
|
export const config = {
|
|
matcher: [
|
|
{
|
|
source: '/api/*',
|
|
regexp: '^/api/(.*)',
|
|
locale: false,
|
|
has: [
|
|
{ type: 'header', key: 'Authorization', value: 'Bearer Token' },
|
|
{ type: 'query', key: 'userId', value: '123' },
|
|
],
|
|
missing: [{ type: 'cookie', key: 'session', value: 'active' }],
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
## Params
|
|
|
|
### `request`
|
|
|
|
When defining Middleware, the default export function accepts a single parameter, `request`. This parameter is an instance of `NextRequest`, which represents the incoming HTTP request.
|
|
|
|
```tsx filename="middleware.ts" switcher
|
|
import type { NextRequest } from 'next/server'
|
|
|
|
export function middleware(request: NextRequest) {
|
|
// Middleware logic goes here
|
|
}
|
|
```
|
|
|
|
```js filename="middleware.js" switcher
|
|
export function middleware(request) {
|
|
// Middleware logic goes here
|
|
}
|
|
```
|
|
|
|
> **Good to know**:
|
|
>
|
|
> - `NextRequest` is a type that represents incoming HTTP requests in Next.js Middleware, whereas [`NextResponse`](#nextresponse) is a class used to manipulate and send back HTTP responses.
|
|
|
|
## NextResponse
|
|
|
|
Middleware can use the [`NextResponse`](/docs/app/building-your-application/routing/middleware#nextresponse) object which extends the [Web Response API](https://developer.mozilla.org/en-US/docs/Web/API/Response). By returning a `NextResponse` object, you can directly manipulate cookies, set headers, implement redirects, and rewrite paths.
|
|
|
|
> **Good to know**: For redirects, you can also use `Response.redirect` instead of `NextResponse.redirect`.
|
|
|
|
## Runtime
|
|
|
|
Middleware only supports the [Edge runtime](/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes). The Node.js runtime cannot be used.
|
|
|
|
## Version History
|
|
|
|
| Version | Changes |
|
|
| --------- | --------------------------------------------------------------------------------------------- |
|
|
| `v13.1.0` | Advanced Middleware flags added |
|
|
| `v13.0.0` | Middleware can modify request headers, response headers, and send responses |
|
|
| `v12.2.0` | Middleware is stable, please see the [upgrade guide](/docs/messages/middleware-upgrade-guide) |
|
|
| `v12.0.9` | Enforce absolute URLs in Edge Runtime ([PR](https://github.com/vercel/next.js/pull/33410)) |
|
|
| `v12.0.0` | Middleware (Beta) added |
|