Unverified Commit 8e161e18 authored by JJ Kasper's avatar JJ Kasper Committed by GitHub

Middleware docs update (#38111)

* Initial outline added for middleware docs

* Feedback changes - not included new user agent yet

* edge api routes docs

* middleware page some cleanup

* moved api stuff to next server, added useragent

* waitUntil example added

* Updated env vars section

* Added cookies on the request object example

* fixed naming

* fixed import typo

* Amy feedback

* Update docs/advanced-features/middleware.md
Co-authored-by: 's avatarAmy Burns <amy.burns@vercel.com>

* first commit

* more fixes

* re-structuring based on feedback

* changes to middleware.md

* updates to edge-api-routes

* code typo

* Update docs/advanced-features/middleware.md
Co-authored-by: 's avatarJJ Kasper <jj@jjsweb.site>

* Update edge-api-routes.md

* Update Edge Runtime API docs

* Clarify API docs

* Update

* Update docs/advanced-features/middleware.md

* Update switchable runtime docs

* Update response

* experimental-edge

* Update docs/advanced-features/middleware.md

* Add example of forwarding headers and address comments

* Add proxying headers to middleware upgrade guide

* Apply suggestions from code review
Co-authored-by: 's avatarJeff Escalante <jescalan@users.noreply.github.com>

* fix middleware directory spec

* localization explanation

* update detecting runtime

* Update docs/advanced-features/react-18/switchable-runtime.md
Co-authored-by: 's avatarBalázs Orbán <info@balazsorban.com>

* fix prettier issues

* table fix

* Update docs/advanced-features/react-18/switchable-runtime.md
Co-authored-by: 's avatarJeff Escalante <jescalan@users.noreply.github.com>

* Update docs/api-routes/edge-api-routes.md
Co-authored-by: 's avatarJeff Escalante <jescalan@users.noreply.github.com>

* lint-fix
Co-authored-by: 's avatarmolebox <hello@richardhaines.dev>
Co-authored-by: 's avatarAmy Burns <amy.burns@vercel.com>
Co-authored-by: 's avatarIsmael Rumzan <ismael.rumzan@gmail.com>
Co-authored-by: 's avatarLee Robinson <me@leerob.io>
Co-authored-by: 's avatarBalázs Orbán <info@balazsorban.com>
Co-authored-by: 's avatarJeff Escalante <jescalan@users.noreply.github.com>
Co-authored-by: 's avatarIsmael <ismael@vercel.com>
parent 632feb6b
--- ---
description: Learn how to use Middleware in Next.js to run code before a request is completed. description: Learn how to use Middleware to run code before a request is completed.
--- ---
# Middleware (Beta) # Middleware
<details open> <details open>
<summary><b>Version History</b></summary> <summary><b>Version History</b></summary>
| Version | Changes | | Version | Changes |
| --------- | ------------------------------------------------------------------------------------------------------- | | --------- | ------------------------------------------------------------------------------------------ |
| `canary` | Preparing for stability, see [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide) | | `v12.2.0` | Middleware is stable |
| `v12.0.9` | Enforce absolute URLs in Edge Runtime ([PR](https://github.com/vercel/next.js/pull/33410)) | | `v12.0.9` | Enforce absolute URLs in Edge Runtime ([PR](https://github.com/vercel/next.js/pull/33410)) |
| `v12.0.0` | Middleware (Beta) added. | | `v12.0.0` | Middleware (Beta) added |
</details> </details>
Middleware enables you to 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. Middleware allows you to run code before a request is completed, then based on the incoming request, you can modify the response by rewriting, redirecting, adding headers, or setting cookies.
## Usage Middleware runs _before_ cached content, so you can personalize static files and pages. Common examples of Middleware would be authentication, A/B testing, localized pages, bot protection, and more. Regarding localized pages, you can start with [i18n routing](/docs/advanced-features/i18n-routing) and implement Middleware for more advanced use cases.
1. Install the canary version of Next.js: > **Note:** If you were using Middleware prior to `12.2`, please see the [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide).
```jsx ## Using Middleware
npm install next@canary
``` To begin using Middleware, follow the steps below:
2. Then, create a `middleware.ts` file under your project root directory. 1. Install the latest version of Next.js:
3. Finally, export a middleware function from the `middleware.ts` file. ```bash
npm install next@latest
```
```jsx 2. Create a `middleware.ts` (or `.js`) file at the same level as your `pages` directory
3. Export a middleware function from the `middleware.ts` file:
```typescript
// middleware.ts // middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
import type { NextRequest, NextResponse } from 'next/server' // This function can be marked `async` if using `await` inside
import { areCredentialsValid } from '../lib' export function middleware(request: NextRequest) {
return NextResponse.redirect(new URL('/about-2', request.url))
}
export function middleware(req: NextRequest) { // See "Matching Paths" below to learn more
if (areCredentialsValid(req.headers.get('authorization'))) { export const config = {
return NextResponse.next() matcher: '/about/:path*',
}
return NextResponse.redirect(
new URL(`/login?from=${req.nextUrl.pathname}`, req.url)
)
} }
``` ```
In this example, we use the standard Web API Response ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response)). ## Matching Paths
## API Middleware will be invoked for **every route in your project**. The following is the execution order:
Middleware is created by using a `middleware` function that lives inside a `middleware` file. Its API is based upon the native [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent), [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), and [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) objects. 1. `headers` from `next.config.js`
2. `redirects` from `next.config.js`
3. Middleware (`rewrites`, `redirects`, etc.)
4. `beforeFiles` (`rewrites`) from `next.config.js`
5. Filesystem routes (`public/`, `_next/static/`, Pages, etc.)
6. `afterFiles` (`rewrites`) from `next.config.js`
7. Dynamic Routes (`/blog/[slug]`)
8. `fallback` (`rewrites`) from `next.config.js`
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. There are two ways to define which paths Middleware will run on:
The function signature: 1. Custom matcher config
2. Conditional statements
```ts ### Matcher
import type { NextFetchEvent } from 'next/server'
import type { NextRequest } from 'next/server'
export type Middleware = ( `matcher` allows you to filter Middleware to run on specific paths.
request: NextRequest,
event: NextFetchEvent ```js
) => Promise<Response | undefined> | Response | undefined export const config = {
matcher: '/about/:path*',
}
``` ```
The function can be a default export and as such, does **not** have to be named `middleware`. Though this is a convention. Also note that you only need to make the function `async` if you are running asynchronous code. You can match a single path or multiple paths with an array syntax:
```js
export const config = {
matcher: ['/about/:path*', '/dashboard/:path*'],
}
```
### Conditional Statements
```typescript
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
if (request.nextUrl.pathname.startsWith('/about')) {
return NextResponse.rewrite(new URL('/about-2', request.url))
}
if (request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.rewrite(new URL('/dashboard/user', request.url))
}
}
```
Read the full [Middleware API reference](/docs/api-reference/edge-runtime.md), note [Node.js APIs are not supported in this environment](/docs/api-reference/edge-runtime.md#unsupported-apis) ## NextResponse
## Examples The [`NextResponse`](#nextresponse) API allows you to:
Middleware can be used for anything that shares logic for a set of pages, including: - `redirect` the incoming request to a different URL
- `rewrite` the response by displaying a given URL
- Set response cookies
- Set response headers
- [Authentication](https://github.com/vercel/examples/tree/main/edge-functions) To produce a response from Middleware, you should `rewrite` to a route ([Page](/docs/basic-features/pages.md) or [Edge API Route](/docs/api-routes/edge-api-routes.md)) that produces a response.
- [Bot protection](https://github.com/vercel/examples/tree/main/edge-functions)
- [Redirects and rewrites](https://github.com/vercel/examples/tree/main/edge-functions)
- [Handling unsupported browsers](https://github.com/vercel/examples/tree/main/edge-functions/user-agent-based-rendering)
- [Feature flags and A/B tests](https://github.com/vercel/examples/tree/main/edge-functions)
- [Advanced i18n routing requirements](https://github.com/vercel/examples/tree/main/edge-functions)
## Execution Order ## Using Cookies
Middleware runs directly after `redirects` and `headers`, before the first filesystem lookup. This excludes `/_next` files. The `cookies` API extends [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) and allows you to `get`, `set`, and `delete` cookies. It also includes methods like [entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries) and [values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries).
## Deployment ```typescript
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
Middleware uses a [strict runtime](/docs/api-reference/edge-runtime.md) 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](http://www.vercel.com/edge). export function middleware(request: NextRequest) {
// Setting cookies on the response
const response = NextResponse.next()
response.cookies.set('vercel', 'fast')
response.cookies.set('vercel', 'fast', { path: '/test' })
// Getting cookies from the request
const cookie = request.cookies.get('vercel')
console.log(cookie) // => 'fast'
const allCookies = request.cookies.entries()
console.log(allCookies) // => [{ key: 'vercel', value: 'fast' }]
const { value, options } = response.cookies.getWithOptions('vercel')
console.log(value) // => 'fast'
console.log(options) // => { Path: '/test' }
// Deleting cookies
response.cookies.delete('vercel')
response.cookies.clear()
return response
}
```
## Related ## Related
<div class="card">
<a href="/docs/api-reference/edge-runtime.md">
<b>Edge Runtime</b>
<small>Learn more about the supported Web APIs available.</small>
</a>
</div>
<div class="card"> <div class="card">
<a href="/docs/api-reference/next/server.md"> <a href="/docs/api-reference/next/server.md">
<b>Middleware API Reference</b> <b>Middleware API Reference</b>
...@@ -98,8 +165,8 @@ Middleware uses a [strict runtime](/docs/api-reference/edge-runtime.md) that sup ...@@ -98,8 +165,8 @@ Middleware uses a [strict runtime](/docs/api-reference/edge-runtime.md) that sup
</div> </div>
<div class="card"> <div class="card">
<a href="/docs/api-reference/edge-runtime.md"> <a href="/docs/api-routes/edge-api-routes.md">
<b>Edge Runtime</b> <b>Edge API Routes</b>
<small>Learn more about the supported Web APIs available.</small> <small>Build high performance APIs in Next.js. </small>
</a> </a>
</div> </div>
# Switchable Runtime (Alpha) # Switchable Runtime (Alpha)
By default, Next.js uses Node.js as the runtime for page rendering, including pre-rendering and server-side rendering. Next.js has two _server runtimes_ to run your application: the **Node.js Runtime** (default) and the [**Edge Runtime**](/docs/api-reference/edge-runtime.md). When server-rendering or serving API routes, the application code will be executed in the Node.js Runtime by default; and for [Middleware](/docs/middleware.md), it will be running in the Edge Runtime.
> Note: `runtime` option only effects pages but not middleware |   | Node (server) | Node (lambda) | Edge |
| ------------------------------------------------------------------------------------------- | ------------- | ------------- | ---------------- |
| [Cold Boot](https://vercel.com/docs/concepts/functions/conceptual-model#cold-and-hot-boots) | / | ~250ms | Instant |
| [HTTP Streaming](https://github.com/reactwg/react-18/discussions/37) | Yes | No | Yes |
| IO | All | All | `fetch` |
| Scalability | / | High | Highest |
| Security | Normal | High | High |
| Latency | Normal | Low | Lowest |
| Code Size | / | 50MB | 1MB |
| NPM Packages | All | All | A smaller subset |
If you have [React 18](/docs/advanced-features/react-18/overview) installed, there is a new experimental feature that lets you switch the page runtime between Node.js and the [Edge Runtime](/docs/api-reference/edge-runtime). Changing the runtime affects [SSR streaming](/docs/advanced-features/react-18/streaming) and [Server Components](/docs/advanced-features/react-18/server-components) features, as well. Next.js' default runtime configuration is good for most use cases, but there’re still many reasons to change to one runtime over the other one. For example, to enable [React 18's](/docs/advanced-features/react-18/overview) [SSR streaming](/docs/advanced-features/react-18/streaming.md) feature, you need to use a runtime that is compatible with Web Streams. For API routes that rely on native Node.js APIs, they need to run with the **Node.js Runtime**. However, if an API only uses something like cookie-based authentication, using Middleware and the [**Edge Runtime**](/docs/api-reference/edge-runtime.md) will be a better choice due to its lower latency as well as better scalability.
Starting with `12.2`, Next.js enables you to customize the runtime for each Next.js route, for both Pages and API routes.
## Global Runtime Option ## Global Runtime Option
...@@ -14,25 +25,63 @@ You can set the experimental option `runtime` to either `'nodejs'` or `'experime ...@@ -14,25 +25,63 @@ You can set the experimental option `runtime` to either `'nodejs'` or `'experime
// next.config.js // next.config.js
module.exports = { module.exports = {
experimental: { experimental: {
runtime: 'nodejs', runtime: 'experimental-edge',
}, },
} }
``` ```
This option determines which runtime should be used as the default rendering runtime for all pages. This option determines which runtime should be used as the default rendering runtime for all pages.
You can detect which runtime you're using by looking at the `process.env.NEXT_RUNTIME` Environment Variable during runtime, and examining the `options.nextRuntime` variable during webpack compilation.
## Page Runtime Option ## Page Runtime Option
On each page, you can optionally export a `runtime` config set to either `'nodejs'` or `'experimental-edge'`: On each page, you can optionally export a `runtime` config set to either `'nodejs'` or `'experimental-edge'`:
```jsx ```jsx
// pages/index.js
export default function Index () { ... }
export function getServerSideProps() { ... }
export const config = { export const config = {
runtime: 'nodejs', runtime: 'experimental-edge',
} }
``` ```
When both the per-page runtime and global runtime are set, the per-page runtime overrides the global runtime. If the per-page runtime is _not_ set, the global runtime option will be used. When both the per-page runtime and global runtime are set, the per-page runtime overrides the global runtime. If the per-page runtime is _not_ set, the global runtime option will be used.
You can refer to the [Switchable Next.js Runtime RFC](https://github.com/vercel/next.js/discussions/34179) for more information. ## Edge API Routes
[Edge API Routes](/docs/api-routes/edge-api-routes.md) enable you to build high performance APIs with Next.js using the Edge Runtime.
```typescript
export const config = {
runtime: 'experimental-edge',
}
export default (req) => new Response('Hello world!')
```
## Related
<div class="card">
<a href="/docs/api-reference/edge-runtime.md">
<b>Edge Runtime</b>
<small>Learn more about the supported Web APIs available.</small>
</a>
</div>
<div class="card">
<a href="/docs/api-reference/next/server.md">
<b>Middleware API Reference</b>
<small>Learn more about the supported APIs for Middleware.</small>
</a>
</div>
**Note:** The page runtime option is not supported in [API Routes](/docs/api-routes/introduction.md) currently. <div class="card">
<a href="/docs/api-routes/edge-api-routes.md">
<b>Edge API Routes</b>
<small>Build high performance APIs in Next.js. </small>
</a>
</div>
This diff is collapsed.
This diff is collapsed.
---
description: Edge API Routes enable you to build high performance APIs directly inside your Next.js application.
---
# Edge API Routes (Beta)
Edge API Routes enable you to build high performance APIs with Next.js. Using the [Edge Runtime](/docs/api-reference/edge-runtime.md), they are often faster than Node.js-based API Routes. This performance improvement does come with [constraints](/docs/api-reference/edge-runtime.md#unsupported-apis), like not having access to native Node.js APIs. Instead, Edge API Routes are built on standard Web APIs.
Any file inside the folder `pages/api` is mapped to `/api/*` and will be treated as an API endpoint instead of a page. They are server-side only bundles and won't increase your client-side bundle size.
## Examples
### Basic
```typescript
export const config = {
runtime: 'experimental-edge',
}
export default (req) => new Response('Hello world!')
```
### JSON Response
```typescript
import type { NextRequest } from 'next/server'
export const config = {
runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
return new Response(
JSON.stringify({
name: 'Jim Halpert',
}),
{
status: 200,
headers: {
'content-type': 'application/json',
},
}
)
}
```
### Cache-Control
```typescript
import type { NextRequest } from 'next/server'
export const config = {
runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
return new Response(
JSON.stringify({
name: 'Jim Halpert',
}),
{
status: 200,
headers: {
'content-type': 'application/json',
'cache-control': 'public, s-maxage=1200, stale-while-revalidate=600',
},
}
)
}
```
### Query Parameters
```typescript
import type { NextRequest } from 'next/server'
export const config = {
runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
const { searchParams } = new URL(req.url)
const email = searchParams.get('email')
return new Response(email)
}
```
### Forwarding Headers
```typescript
import { type NextRequest } from 'next/server'
export const config = {
runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
const authorization = req.cookies.get('authorization')
return fetch('https://backend-api.com/api/protected', {
method: req.method,
headers: {
authorization,
},
redirect: 'manual',
})
}
```
## Differences between API Routes
Edge API Routes use the [Edge Runtime](/docs/api-reference/edge-runtime.md), whereas API Routes use the [Node.js runtime](/docs/advanced-features/react-18/switchable-runtime.md).
Edge API Routes can [stream responses](/docs/api-reference/edge-runtime.md#web-stream-apis) from the server and run _after_ cached files (e.g. HTML, CSS, JavaScript) have been accessed. Server-side streaming can help improve performance with faster [Time To First Byte (TTFB)](https://web.dev/ttfb/).
View the [supported APIs](/docs/api-reference/edge-runtime.md) and [unsupported APIs](/docs/api-reference/edge-runtime.md#unsupported-apis) for the Edge Runtime.
...@@ -4,7 +4,10 @@ ...@@ -4,7 +4,10 @@
"title": "Documentation", "title": "Documentation",
"heading": true, "heading": true,
"routes": [ "routes": [
{ "title": "Getting Started", "path": "/docs/getting-started.md" }, {
"title": "Getting Started",
"path": "/docs/getting-started.md"
},
{ {
"title": "Basic Features", "title": "Basic Features",
"open": true, "open": true,
...@@ -139,6 +142,10 @@ ...@@ -139,6 +142,10 @@
{ {
"title": "Response Helpers", "title": "Response Helpers",
"path": "/docs/api-routes/response-helpers.md" "path": "/docs/api-routes/response-helpers.md"
},
{
"title": "Edge API Routes (Beta)",
"path": "/docs/api-routes/edge-api-routes.md"
} }
] ]
}, },
...@@ -271,7 +278,7 @@ ...@@ -271,7 +278,7 @@
"path": "/docs/advanced-features/measuring-performance.md" "path": "/docs/advanced-features/measuring-performance.md"
}, },
{ {
"title": "Middleware (Beta)", "title": "Middleware",
"path": "/docs/advanced-features/middleware.md" "path": "/docs/advanced-features/middleware.md"
}, },
{ {
...@@ -356,14 +363,20 @@ ...@@ -356,14 +363,20 @@
} }
] ]
}, },
{ "title": "FAQ", "path": "/docs/faq.md" } {
"title": "FAQ",
"path": "/docs/faq.md"
}
] ]
}, },
{ {
"title": "API Reference", "title": "API Reference",
"heading": true, "heading": true,
"routes": [ "routes": [
{ "title": "CLI", "path": "/docs/api-reference/cli.md" }, {
"title": "CLI",
"path": "/docs/api-reference/cli.md"
},
{ {
"title": "Create Next App", "title": "Create Next App",
"path": "/docs/api-reference/create-next-app.md" "path": "/docs/api-reference/create-next-app.md"
......
...@@ -84,7 +84,7 @@ export function middleware(request: NextRequest) { ...@@ -84,7 +84,7 @@ export function middleware(request: NextRequest) {
### Summary of changes ### Summary of changes
- Middleware can no longer respond with a body - Middleware can no longer produce a response body
- If your Middleware _does_ respond with a body, a runtime error will be thrown - If your Middleware _does_ respond with a body, a runtime error will be thrown
- Migrate to using `rewrite`/`redirect` to pages/APIs handling a response - Migrate to using `rewrite`/`redirect` to pages/APIs handling a response
...@@ -144,6 +144,31 @@ export function middleware(request: NextRequest) { ...@@ -144,6 +144,31 @@ export function middleware(request: NextRequest) {
} }
``` ```
#### Edge API Routes
If you were previously using Middleware to forward headers to an external API, you can now use [Edge API Routes](/docs/api-routes/edge-api-routes):
```typescript
// pages/api/proxy.ts
import { type NextRequest } from 'next/server'
export const config = {
runtime: 'experimental-edge',
}
export default async function handler(req: NextRequest) {
const authorization = req.cookies.get('authorization')
return fetch('https://backend-api.com/api/protected', {
method: req.method,
headers: {
authorization,
},
redirect: 'manual',
})
}
```
## Cookies API Revamped ## Cookies API Revamped
### Summary of changes ### Summary of changes
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment