Skip to content

Commit

Permalink
docs: inform middleware usage along with metadata files (vercel#69136)
Browse files Browse the repository at this point in the history
### What?

When the user sets `robots.ts`, `sitemap.ts`, or other metadata files with `middleware.ts`, it may end in unexpected behavior if the middleware matcher is not set to ignore the corresponding paths.

### Why? 

The docs are missing the information for the users to "**configure middleware matcher if you have one along with generating metadata files to prevent route interference**".

### How?

Updated the docs to add the matcher configuration as:

```ts
export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files) <--- combined here
     */
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
}
```

Added a "Good to Know" at the [entry of metadata API](https://nextjs.org/docs/app/api-reference/file-conventions/metadata) to configure the middleware matcher if used.

Closes NDX-219
  • Loading branch information
devjiwonchoi authored Aug 21, 2024
1 parent c58c847 commit 8ff0b37
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 7 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -110,9 +110,9 @@ export const config = {
* - api (API routes)
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico (favicon file)
* - favicon.ico, sitemap.xml, robots.txt (metadata files)
*/
'/((?!api|_next/static|_next/image|favicon.ico).*)',
'/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
],
}
```
Expand All @@ -127,26 +127,29 @@ export const config = {
* - api (API routes)
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico (favicon file)
* - favicon.ico, sitemap.xml, robots.txt (metadata files)
*/
{
source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
source:
'/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
missing: [
{ type: 'header', key: 'next-router-prefetch' },
{ type: 'header', key: 'purpose', value: 'prefetch' },
],
},

{
source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
source:
'/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
has: [
{ type: 'header', key: 'next-router-prefetch' },
{ type: 'header', key: 'purpose', value: 'prefetch' },
],
},

{
source: '/((?!api|_next/static|_next/image|favicon.ico).*)',
source:
'/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
has: [{ type: 'header', key: 'x-present' }],
missing: [{ type: 'header', key: 'x-missing', value: 'prefetch' }],
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,7 @@ Each file convention can be defined using a static file (e.g. `opengraph-image.j

Once a file is defined, Next.js will automatically serve the file (with hashes in production for caching) and update the relevant head elements with the correct metadata, such as the asset's URL, file type, and image size.

> **Good to know**: Special Route Handlers like [`sitemap.ts`](/docs/app/api-reference/file-conventions/metadata/sitemap), [`opengraph-image.tsx`](/docs/app/api-reference/file-conventions/metadata/opengraph-image), and [`icon.tsx`](/docs/app/api-reference/file-conventions/metadata/app-icons), and other [metadata files](/docs/app/api-reference/file-conventions/metadata) are cached by default.
> **Good to know**:
>
> - Special Route Handlers like [`sitemap.ts`](/docs/app/api-reference/file-conventions/metadata/sitemap), [`opengraph-image.tsx`](/docs/app/api-reference/file-conventions/metadata/opengraph-image), and [`icon.tsx`](/docs/app/api-reference/file-conventions/metadata/app-icons), and other [metadata files](/docs/app/api-reference/file-conventions/metadata) are cached by default.
> - If using along with [`middleware.ts`](/docs/app/api-reference/file-conventions/middleware), [configure the matcher](/docs/app/building-your-application/routing/middleware#matcher) to exclude the metadata files.

0 comments on commit 8ff0b37

Please sign in to comment.