Unverified Commit 7b84d63e authored by JJ Kasper's avatar JJ Kasper Committed by GitHub

Add docs for missing support on custom routes (#44007)

x-ref: https://github.com/vercel/next.js/pull/42660

## Documentation / Examples

- [x] Make sure the linting passes by running `pnpm build && pnpm lint`
- [x] The "examples guidelines" are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md)
parent 0269f1cb
...@@ -54,6 +54,7 @@ module.exports = { ...@@ -54,6 +54,7 @@ module.exports = {
- `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only. - `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only.
- `locale`: `false` or `undefined` - whether the locale should not be included when matching. - `locale`: `false` or `undefined` - whether the locale should not be included when matching.
- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties. - `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
- `missing` is an array of [missing objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
Headers are checked before the filesystem which includes pages and `/public` files. Headers are checked before the filesystem which includes pages and `/public` files.
...@@ -185,9 +186,9 @@ module.exports = { ...@@ -185,9 +186,9 @@ module.exports = {
## Header, Cookie, and Query Matching ## Header, Cookie, and Query Matching
To only apply a header when either header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the header to be applied. To only apply a header when header, cookie, or query values also match the `has` field or don't match the `missing` field can be used. Both the `source` and all `has` items must match and all `missing` items must not match for the header to be applied.
`has` items have the following fields: `has` and `missing` items can have the following fields:
- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`. - `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
- `key`: `String` - the key from the selected type to match against. - `key`: `String` - the key from the selected type to match against.
...@@ -214,6 +215,23 @@ module.exports = { ...@@ -214,6 +215,23 @@ module.exports = {
}, },
], ],
}, },
// if the header `x-no-header` is not present,
// the `x-another-header` header will be applied
{
source: '/:path*',
missing: [
{
type: 'header',
key: 'x-no-header',
},
],
headers: [
{
key: 'x-another-header',
value: 'hello',
},
],
},
// if the source, query, and cookie are matched, // if the source, query, and cookie are matched,
// the `x-authorized` header will be applied // the `x-authorized` header will be applied
{ {
......
...@@ -50,6 +50,7 @@ module.exports = { ...@@ -50,6 +50,7 @@ module.exports = {
- `basePath`: `false` or `undefined` - if false the `basePath` won't be included when matching, can be used for external redirects only. - `basePath`: `false` or `undefined` - if false the `basePath` won't be included when matching, can be used for external redirects only.
- `locale`: `false` or `undefined` - whether the locale should not be included when matching. - `locale`: `false` or `undefined` - whether the locale should not be included when matching.
- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties. - `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
- `missing` is an array of [missing objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
Redirects are checked before the filesystem which includes pages and `/public` files. Redirects are checked before the filesystem which includes pages and `/public` files.
...@@ -140,9 +141,9 @@ module.exports = { ...@@ -140,9 +141,9 @@ module.exports = {
## Header, Cookie, and Query Matching ## Header, Cookie, and Query Matching
To only match a redirect when header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the redirect to be applied. To only match a redirect when header, cookie, or query values also match the `has` field or don't match the `missing` field can be used. Both the `source` and all `has` items must match and all `missing` items must not match for the redirect to be applied.
`has` items have the following fields: `has` and `missing` items can have the following fields:
- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`. - `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
- `key`: `String` - the key from the selected type to match against. - `key`: `String` - the key from the selected type to match against.
...@@ -165,6 +166,19 @@ module.exports = { ...@@ -165,6 +166,19 @@ module.exports = {
permanent: false, permanent: false,
destination: '/another-page', destination: '/another-page',
}, },
// if the header `x-dont-redirect` is present,
// this redirect will be applied
{
source: '/:path((?!another-page$).*)',
missing: [
{
type: 'header',
key: 'x-do-not-redirect',
},
],
permanent: false,
destination: '/another-page',
},
// if the source, query, and cookie are matched, // if the source, query, and cookie are matched,
// this redirect will be applied // this redirect will be applied
{ {
......
...@@ -15,7 +15,8 @@ description: Add rewrites to your Next.js app. ...@@ -15,7 +15,8 @@ description: Add rewrites to your Next.js app.
<summary><b>Version History</b></summary> <summary><b>Version History</b></summary>
| Version | Changes | | Version | Changes |
| --------- | --------------- | | --------- | ---------------- |
| `v13.3.0` | `missing` added. |
| `v10.2.0` | `has` added. | | `v10.2.0` | `has` added. |
| `v9.5.0` | Rewrites added. | | `v9.5.0` | Rewrites added. |
...@@ -49,6 +50,7 @@ Rewrites are applied to client-side routing, a `<Link href="/about">` will have ...@@ -49,6 +50,7 @@ Rewrites are applied to client-side routing, a `<Link href="/about">` will have
- `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only. - `basePath`: `false` or `undefined` - if false the basePath won't be included when matching, can be used for external rewrites only.
- `locale`: `false` or `undefined` - whether the locale should not be included when matching. - `locale`: `false` or `undefined` - whether the locale should not be included when matching.
- `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties. - `has` is an array of [has objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
- `missing` is an array of [missing objects](#header-cookie-and-query-matching) with the `type`, `key` and `value` properties.
When the `rewrites` function returns an array, rewrites are applied after checking the filesystem (pages and `/public` files) and before dynamic routes. When the `rewrites` function returns an object of arrays with a specific shape, this behavior can be changed and more finely controlled, as of `v10.1` of Next.js: When the `rewrites` function returns an array, rewrites are applied after checking the filesystem (pages and `/public` files) and before dynamic routes. When the `rewrites` function returns an object of arrays with a specific shape, this behavior can be changed and more finely controlled, as of `v10.1` of Next.js:
...@@ -219,9 +221,9 @@ module.exports = { ...@@ -219,9 +221,9 @@ module.exports = {
## Header, Cookie, and Query Matching ## Header, Cookie, and Query Matching
To only match a rewrite when header, cookie, or query values also match the `has` field can be used. Both the `source` and all `has` items must match for the rewrite to be applied. To only match a rewrite when header, cookie, or query values also match the `has` field or don't match the `missing` field can be used. Both the `source` and all `has` items must match and all `missing` items must not match for the rewrite to be applied.
`has` items have the following fields: `has` and `missing` items can have the following fields:
- `type`: `String` - must be either `header`, `cookie`, `host`, or `query`. - `type`: `String` - must be either `header`, `cookie`, `host`, or `query`.
- `key`: `String` - the key from the selected type to match against. - `key`: `String` - the key from the selected type to match against.
...@@ -243,6 +245,18 @@ module.exports = { ...@@ -243,6 +245,18 @@ module.exports = {
], ],
destination: '/another-page', destination: '/another-page',
}, },
// if the header `x-rewrite-me` is not present,
// this rewrite will be applied
{
source: '/:path*',
missing: [
{
type: 'header',
key: 'x-rewrite-me',
},
],
destination: '/another-page',
},
// if the source, query, and cookie are matched, // if the source, query, and cookie are matched,
// this rewrite will be applied // this rewrite will be applied
{ {
......
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