docs: Fix suggested middleware matcher regex and add matcher docs (#505)

Fixes #504

Author: amannn

docs/pages/docs/getting-started/app-router-client-components.mdx

@@ -56,12 +56,14 @@ export default createMiddleware({
 });
 
 export const config = {
-  // Skip all paths that should not be internationalized. This example skips the
-  // folders "api", "_next" and all files with an extension (e.g. favicon.ico)
-  matcher: ['/((?!api|_next|.*\\..*).*)']
+  // Skip all paths that should not be internationalized. This example skips
+  // certain folders and all pathnames with a dot (e.g. favicon.ico)
+  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)']
 };
 ```
 
+**Note:** If you have pages that contain the character `.` in the pathname (e.g. `/users/jane.doe`), you might want to consider them in your [matcher config](/docs/routing/middleware#matcher-config).
+
 ### `app/[locale]/layout.tsx` [#next-intl-client-provider]
 
 Provide the document layout and set up `NextIntlClientProvider`.

docs/pages/docs/getting-started/app-router-server-components.mdx

@@ -113,12 +113,14 @@ export default createMiddleware({
 });
 
 export const config = {
-  // Skip all paths that should not be internationalized. This example skips the
-  // folders "api", "_next" and all files with an extension (e.g. favicon.ico)
-  matcher: ['/((?!api|_next|.*\\..*).*)']
+  // Skip all paths that should not be internationalized. This example skips
+  // certain folders and all pathnames with a dot (e.g. favicon.ico)
+  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)']
 };
 ```
 
+**Note:** If you have pages that contain the character `.` in the pathname (e.g. `/users/jane.doe`), you might want to consider them in your [matcher config](/docs/routing/middleware#matcher-config).
+
 ### `app/[locale]/layout.tsx`
 
 The `locale` that was matched by the middleware is available via `useLocale` and can be used to configure the document language.

docs/pages/docs/routing/middleware.mdx

@@ -16,9 +16,9 @@ export default createMiddleware({
 });
 
 export const config = {
-  // Skip all paths that should not be internationalized. This example skips the
-  // folders "api", "_next" and all files with an extension (e.g. favicon.ico)
-  matcher: ['/((?!api|_next|.*\\..*).*)']
+  // Skip all paths that should not be internationalized. This example skips
+  // certain folders and all pathnames with a dot (e.g. favicon.ico)
+  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)']
 };
 ```
 
@@ -261,6 +261,39 @@ export default createMiddleware({
   APIs](/docs/routing/navigation#localized-pathnames) in your components.
 </Callout>
 
+### Matcher config
+
+The middleware is intended to only run on pages, not on arbitrary files that you serve independently of the user locale (e.g. `/favicon.ico`).
+
+Because of this, the following config is generally recommended:
+
+```tsx filename="middleware.ts"
+export const config = {
+  // Skip all paths that should not be internationalized. This example skips
+  // certain folders and all pathnames with a dot (e.g. favicon.ico)
+  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)']
+};
+```
+
+However, this can lead to false negatives if you have pages that contain the character `.` (e.g. `/users/jane.doe`). To make sure these are processed by the middleware, you can add corresponding entries to the matcher config:
+
+```tsx filename="middleware.ts"
+export const config = {
+  // Matcher entries are linked with a logical "or", therefore
+  // if one of them matches, the middleware will be invoked.
+  matcher: [
+    // Match all pathnames without `.`
+    '/((?!api|_next|_vercel|.*\\..*).*)',
+    // Match all pathnames within `/users`, optionally with a locale prefix
+    '/(.+)?/users/(.+)'
+  ]
+};
+```
+
+{/* Keep this in sync with `packages/next-intl/test/middleware/middleware.test.tsx` */}
+
+Additionally, some third-party providers like [Vercel Analytics](https://vercel.com/analytics) and [umami](https://umami.is/docs/running-on-vercel) typically use internal endpoints that are then rewritten to an external URL (e.g. `/_vercel/insights/view`). Make sure to exclude such requests from your middleware matcher so they aren't accidentally rewritten.
+
 ## Composing other middlewares
 
 By calling `createMiddleware`, you'll receive a function of the following type:

examples/example-next-13/src/middleware.tsx

@@ -7,5 +7,5 @@ export default createMiddleware({
 
 export const config = {
   // Skip all paths that should not be internationalized
-  matcher: ['/((?!api|_next|.*\\..*).*)']
+  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)']
 };

packages/next-intl/package.json

@@ -85,6 +85,7 @@
     "eslint-config-molindo": "^7.0.0",
     "eslint-plugin-deprecation": "^1.4.1",
     "next": "13.5.1",
+    "path-to-regexp": "^6.2.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "size-limit": "^8.2.6",

packages/next-intl/test/middleware/middleware.test.tsx

@@ -1,5 +1,6 @@
 import {RequestCookies} from 'next/dist/compiled/@edge-runtime/cookies';
 import {NextRequest, NextResponse} from 'next/server';
+import {pathToRegexp} from 'path-to-regexp';
 import {it, describe, vi, beforeEach, expect, Mock} from 'vitest';
 import createIntlMiddleware from '../../src/middleware';
 import {COOKIE_LOCALE_NAME} from '../../src/shared/constants';
@@ -68,6 +69,59 @@ beforeEach(() => {
   vi.clearAllMocks();
 });
 
+it('has docs that suggest a reasonable matcher', () => {
+  const matcherFromDocs = [
+    // Match all pathnames without `.`
+    '/((?!api|_next|_vercel|.*\\..*).*)',
+    // Match all pathnames within `/users`, optionally with a locale prefix
+    '/(.+)?/users/(.+)'
+  ];
+
+  const test = [
+    ['/', true],
+    ['/test', true],
+    ['/de/test', true],
+    ['/something/else', true],
+    ['/encoded%20BV', true],
+    ['/users/jane.doe', true],
+    ['/de/users/jane.doe', true],
+    ['/users/jane.doe/profile', true],
+
+    ['/favicon.ico', false],
+    ['/icon.ico', false],
+    ['/icon.png', false],
+    ['/icon.jpg', false],
+    ['/icon.jpeg', false],
+    ['/icon.svg', false],
+    ['/apple-icon.png', false],
+    ['/manifest.json', false],
+    ['/manifest.webmanifest', false],
+    ['/opengraph-image.gif', false],
+    ['/twitter-image.png', false],
+    ['/robots.txt', false],
+    ['/sitemap.xml', false],
+    ['/portraits/jane.webp', false],
+    ['/something/dot.', false],
+    ['/.leading-dot', false],
+    ['/api/auth', false],
+    ['/_vercel/insights/script.js', false],
+    ['/_vercel/insights/view', false],
+    ['/test.html', false],
+    ['/_next/static/chunks/main-app-123.js?23', false],
+    ['/test.html?searchParam=2', false],
+    ['/hello/text.txt', false]
+  ] as const;
+
+  expect(
+    test.map(([pathname]) => {
+      const matches = matcherFromDocs.some((pattern) =>
+        pathname.match(pathToRegexp(pattern))
+      );
+      return pathname + ': ' + matches;
+    })
+  ).toEqual(test.map(([pathname, expected]) => pathname + ': ' + expected));
+});
+
 describe('prefix-based routing', () => {
   describe('localePrefix: as-needed', () => {
     const middleware = createIntlMiddleware({