Add custom routes docs (rewrites, redirects, headers) (#14887)

Fixes #14452

Author: timneutkens

docs/api-reference/next.config.js/headers.md

@@ -0,0 +1,91 @@
+---
+description: Add custom HTTP headers to your Next.js app.
+---
+
+# Headers
+
+Headers allow you to set custom HTTP headers for an incoming request path.
+
+To set custom HTTP headers you can use the `headers` key in `next.config.js`:
+
+```js
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/about',
+        headers: [
+          {
+            key: 'x-custom-header',
+            value: 'my custom header value',
+          },
+          {
+            key: 'x-another-custom-header',
+            value: 'my other custom header value',
+          },
+        ],
+      },
+      ,
+    ]
+  },
+}
+```
+
+`headers` is an async function that expects an array to be returned holding objects with `source` and `headers` properties:
+
+- `source` is the incoming request path pattern.
+- `headers` is an array of header objects with the `key` and `value` properties.
+
+## Path Matching
+
+Path matches are allowed, for example `/blog/:slug` will match `/blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/blog/:slug',
+        headers: [
+          {
+            key: 'x-slug',
+            value: ':slug', // Matched parameters can be used in the value
+          },
+          {
+            key: 'x-slug-:slug', // Matched parameters can be used in the key
+            value: 'my other custom header value',
+          },
+        ],
+      },
+      ,
+    ]
+  },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/blog/:slug*',
+        headers: [
+          {
+            key: 'x-slug',
+            value: ':slug*', // Matched parameters can be used in the value
+          },
+          {
+            key: 'x-slug-:slug*', // Matched parameters can be used in the key
+            value: 'my other custom header value',
+          },
+        ],
+      },
+      ,
+    ]
+  },
+}
+```

docs/api-reference/next.config.js/redirects.md

@@ -0,0 +1,67 @@
+---
+description: Add redirects to your Next.js app.
+---
+
+# Redirects
+
+Redirects allow you to redirect an incoming request path to a different destination path.
+
+Redirects are only available on the Node.js environment and do not affect client-side routing.
+
+To use Redirects you can use the `redirects` key in `next.config.js`:
+
+```js
+module.exports = {
+  async redirects() {
+    return [
+      {
+        source: '/about',
+        destination: '/',
+        permanent: true,
+      },
+    ]
+  },
+}
+```
+
+`redirects` is an async function that expects an array to be returned holding objects with `source`, `destination`, and `permanent` properties:
+
+- `source` is the incoming request path pattern.
+- `destination` is the path you want to route to.
+- `permanent` if the redirect is permanent or not.
+
+## Path Matching
+
+Path matches are allowed, for example `/old-blog/:slug` will match `/old-blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+  async redirects() {
+    return [
+      {
+        source: '/old-blog/:slug',
+        destination: '/news/:slug', // Matched parameters can be used in the destination
+        permanent: true,
+      },
+    ]
+  },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+  async redirects() {
+    return [
+      {
+        source: '/blog/:slug*',
+        destination: '/news/:slug*', // Matched parameters can be used in the destination
+        permanent: true,
+      },
+    ]
+  },
+}
+```

docs/api-reference/next.config.js/rewrites.md

@@ -0,0 +1,112 @@
+---
+description: Add rewrites to your Next.js app.
+---
+
+# Rewrites
+
+Rewrites allow you to map an incoming request path to a different destination path.
+
+Rewrites are only available on the Node.js environment and do not affect client-side routing.
+
+To use rewrites you can use the `rewrites` key in `next.config.js`:
+
+```js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/about',
+        destination: '/',
+      },
+    ]
+  },
+}
+```
+
+`rewrites` is an async function that expects an array to be returned holding objects with `source` and `destination` properties:
+
+- `source` is the incoming request path pattern.
+- `destination` is the path you want to route to.
+
+## Path Matching
+
+Path matches are allowed, for example `/blog/:slug` will match `/blog/hello-world` (no nested paths):
+
+```js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/blog/:slug',
+        destination: '/news/:slug', // Matched parameters can be used in the destination
+      },
+    ]
+  },
+}
+```
+
+### Wildcard Path Matching
+
+To match a wildcard path you can use `*` after a parameter, for example `/blog/:slug*` will match `/blog/a/b/c/d/hello-world`:
+
+```js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/blog/:slug*',
+        destination: '/news/:slug*', // Matched parameters can be used in the destination
+      },
+    ]
+  },
+}
+```
+
+## Rewriting to an external URL
+
+<details>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/custom-routes-proxying">Incremental adoption of Next.js</a></li>
+  </ul>
+</details>
+
+Rewrites allow you to rewrite to an external url. This is especially useful for incrementally adopting Next.js.
+
+```js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/blog/:slug',
+        destination: 'https://example.com/blog/:slug', // Matched parameters can be used in the destination
+      },
+    ]
+  },
+}
+```
+
+### Incremental adoption of Next.js
+
+You can also make Next.js check the application routes before falling back to proxying to the previous website.
+
+This way you don't have to change the rewrites configuration when migrating more pages to Next.js
+
+```js
+module.exports = {
+  async rewrites() {
+    return [
+      // we need to define a no-op rewrite to trigger checking
+      // all pages/static files before we attempt proxying
+      {
+        source: '/:path*',
+        destination: '/:path*',
+      },
+      {
+        source: '/:path*',
+        destination: `https://custom-routes-proxying-endpoint.vercel.app/:path*`,
+      },
+    ]
+  },
+}
+```

docs/manifest.json

@@ -231,6 +231,18 @@
               "title": "Base Path",
               "path": "/docs/api-reference/next.config.js/basepath.md"
             },
+            {
+              "title": "Rewrites",
+              "path": "/docs/api-reference/next.config.js/rewrites.md"
+            },
+            {
+              "title": "Redirects",
+              "path": "/docs/api-reference/next.config.js/redirects.md"
+            },
+            {
+              "title": "Custom Headers",
+              "path": "/docs/api-reference/next.config.js/headers.md"
+            },
             {
               "title": "Custom Page Extensions",
               "path": "/docs/api-reference/next.config.js/custom-page-extensions.md"