docs: documents middleware matcher (#40180)
### 📖 What's in there?
Middleware matchers are powerful, but very few people realized it, because they are not really documented.
This PR tries to bring more clarity, and includes a more advanced example.
The example shows how to exclude several pages (no `/static`, no `/public`), but also allow specific page in excluded paths (`/public/disclaimer`)
### 🧪 How to test?
Run the example: `pnpm next dev examples/middleware-matcher`, then browse to http://localhost:3000
The first 3 links should not match, the last 3 ones should.
Don't forget to clear your localhost cookies if you change the middleware code.
### 🆙 Note to reviewers
Using session cookies to pass information from middleware to the rendered page is not great, because `document.cookie` is not available during SSR, and because cookies persist when refreshing the page (making it hard to try different matchers)
However, I couldn't find a simpler way to convey the information from the middleware to the page, and I meant to have something visual. The other option is to use response headers and curl commands, but...
2022-09-05 15:36:09 +02:00
# Middleware
This example shows how to configure your [Next.js Middleware ](https://nextjs.org/docs/advanced-features/middleware ) to only match specific pages.
2022-11-06 07:08:06 +01:00
The index page ([`pages/index.ts`](pages/index.ts)) has a list of links to dynamic pages, which will tell whether they were matched or not.
docs: documents middleware matcher (#40180)
### 📖 What's in there?
Middleware matchers are powerful, but very few people realized it, because they are not really documented.
This PR tries to bring more clarity, and includes a more advanced example.
The example shows how to exclude several pages (no `/static`, no `/public`), but also allow specific page in excluded paths (`/public/disclaimer`)
### 🧪 How to test?
Run the example: `pnpm next dev examples/middleware-matcher`, then browse to http://localhost:3000
The first 3 links should not match, the last 3 ones should.
Don't forget to clear your localhost cookies if you change the middleware code.
### 🆙 Note to reviewers
Using session cookies to pass information from middleware to the rendered page is not great, because `document.cookie` is not available during SSR, and because cookies persist when refreshing the page (making it hard to try different matchers)
However, I couldn't find a simpler way to convey the information from the middleware to the page, and I meant to have something visual. The other option is to use response headers and curl commands, but...
2022-09-05 15:36:09 +02:00
2022-11-06 07:08:06 +01:00
The Middleware file ([`middleware.ts`](middleware.ts)) has a special `matcher` configuration key, allowing you to fine-grained control [matched pages ](https://nextjs.org/docs/advanced-features/middleware#matcher ).
docs: documents middleware matcher (#40180)
### 📖 What's in there?
Middleware matchers are powerful, but very few people realized it, because they are not really documented.
This PR tries to bring more clarity, and includes a more advanced example.
The example shows how to exclude several pages (no `/static`, no `/public`), but also allow specific page in excluded paths (`/public/disclaimer`)
### 🧪 How to test?
Run the example: `pnpm next dev examples/middleware-matcher`, then browse to http://localhost:3000
The first 3 links should not match, the last 3 ones should.
Don't forget to clear your localhost cookies if you change the middleware code.
### 🆙 Note to reviewers
Using session cookies to pass information from middleware to the rendered page is not great, because `document.cookie` is not available during SSR, and because cookies persist when refreshing the page (making it hard to try different matchers)
However, I couldn't find a simpler way to convey the information from the middleware to the page, and I meant to have something visual. The other option is to use response headers and curl commands, but...
2022-09-05 15:36:09 +02:00
Please keep in mind that:
1. Middleware always runs first
1. Middleware always matches `_next` routes on server side
1. matcher must always starts with a '/'
## Deploy your own
Deploy the example using [Vercel ](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example ):
[![Deploy with Vercel ](https://vercel.com/button )](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/middleware-matcher& project-name=middleware-matcher& repository-name=middleware-matcher)
## How to use
Execute [`create-next-app` ](https://github.com/vercel/next.js/tree/canary/packages/create-next-app ) with [npm ](https://docs.npmjs.com/cli/init ), [Yarn ](https://yarnpkg.com/lang/en/docs/cli/create/ ), or [pnpm ](https://pnpm.io ) to bootstrap the example:
```bash
npx create-next-app --example middleware-matcher middleware-matcher-app
```
```bash
yarn create next-app --example middleware-matcher middleware-matcher-app
```
```bash
pnpm create next-app --example middleware-matcher middleware-matcher-app
```
Deploy it to the cloud with [Vercel ](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example ) ([Documentation](https://nextjs.org/docs/deployment)).