From ff5ad8572a234d07f3189dfe1adb4931698f9b50 Mon Sep 17 00:00:00 2001 From: hiro08gh Date: Sun, 20 Feb 2022 15:25:02 +0900 Subject: [PATCH] add: middleware.md --- docs/manifest.json | 21 ++++++-- docs/middleware.md | 125 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+), 4 deletions(-) create mode 100644 docs/middleware.md diff --git a/docs/manifest.json b/docs/manifest.json index b7663c27..6e2cd95e 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -4,7 +4,10 @@ "title": "Documentation", "heading": true, "routes": [ - { "title": "はじめに", "path": "/docs/getting-started.md" }, + { + "title": "はじめに", + "path": "/docs/getting-started.md" + }, { "title": "Basic Features", "open": true, @@ -89,6 +92,10 @@ } ] }, + { + "title": "Middleware", + "path": "/docs/middleware.md" + }, { "title": "Deployment", "path": "/docs/deployment.md" @@ -240,14 +247,20 @@ } ] }, - { "title": "よくある質問", "path": "/docs/faq.md" } + { + "title": "よくある質問", + "path": "/docs/faq.md" + } ] }, { "title": "API Reference", "heading": true, "routes": [ - { "title": "CLI", "path": "/docs/api-reference/cli.md" }, + { + "title": "CLI", + "path": "/docs/api-reference/cli.md" + }, { "title": "Create Next App", "path": "/docs/api-reference/create-next-app.md" @@ -401,4 +414,4 @@ ] } ] -} +} \ No newline at end of file diff --git a/docs/middleware.md b/docs/middleware.md new file mode 100644 index 00000000..efa7dac8 --- /dev/null +++ b/docs/middleware.md @@ -0,0 +1,125 @@ +--- +description: Learn how to use Middleware in Next.js to run code before a request is completed. +--- + +# Middleware + +
+ Version History + +| Version | Changes | +| --------- | ------------------------------------------------------------------------------------------ | +| `v12.0.9` | Enforce absolute URLs in Edge Runtime ([PR](https://github.com/vercel/next.js/pull/33410)) | +| `v12.0.0` | Middleware (Beta) added. | + +
+ +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. + +## Usage + +1. Install the latest version of Next.js: + +```jsx +npm install next@latest +``` + +2. Then, create a `_middleware.ts` file under your `/pages` directory. + +3. Finally, export a middleware function from the `_middleware.ts` file. + +```jsx +// 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](https://developer.mozilla.org/en-US/docs/Web/API/Response)). + +## API + +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. + +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. + +The function signature: + +```ts +import type { NextFetchEvent } from 'next/server' +import type { NextRequest } from 'next/server' + +export type Middleware = ( + request: NextRequest, + event: NextFetchEvent +) => Promise | Response | undefined +``` + +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. + +[Read the full Middleware API reference.](/docs/api-reference/next/server.md) + +## Examples + +Middleware can be used for anything that shares logic for a set of pages, including: + +- [Authentication](https://github.com/vercel/examples/tree/main/edge-functions) +- [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) +- [Feature flags and A/B tests](https://github.com/vercel/examples/tree/main/edge-functions) +- [Server-side analytics](https://github.com/vercel/examples/tree/main/edge-functions) +- [Advanced i18n routing requirements](https://github.com/vercel/examples/tree/main/edge-functions) +- [Logging](https://github.com/vercel/examples/tree/main/edge-functions) + +## 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. + +```bash +- 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. + +```bash +- 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. + +## Deployment + +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). + +## Related + +
+ + Middleware API Reference + Learn more about the supported APIs for Middleware. + +
+ +
+ + Edge Runtime + Learn more about the supported Web APIs available. + +
\ No newline at end of file