Merge remote-tracking branch 'upstream/canary' into wip-remove-url

docs/advanced-features/preview-mode.md

@@ -111,8 +111,7 @@ export default async (req, res) => {
 
   // Redirect to the path from the fetched post
   // We don't redirect to req.query.slug as that might lead to open redirect vulnerabilities
-  res.writeHead(307, { Location: post.slug })
-  res.end()
+  res.redirect(post.slug)
 }
 ```
 

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

@@ -0,0 +1,43 @@
+---
+description: Learn more about setting a base path in Next.js
+---
+
+# Base Path
+
+To deploy a Next.js application under a sub-path of a domain you can use the `basePath` option.
+
+`basePath` allows you to set a path prefix for the application. For example `/docs` instead of `/` (the default).
+
+For example, to set the base path to `/docs`, set the following configuration in `next.config.js`:
+
+```js
+module.exports = {
+  basePath: '/docs',
+}
+```
+
+## Links
+
+When linking to other pages using `next/link` and `next/router` the `basePath` will be automatically applied.
+
+For example using `/about` will automatically become `/docs/about` when `basePath` is set to `/docs`.
+
+```js
+export default function HomePage() {
+  return (
+    <>
+      <Link href="/about">
+        <a>About Page</a>
+      </Link>
+    </>
+  )
+}
+```
+
+Output html:
+
+```html
+<a href="/docs/about">About Page</a>
+```
+
+This makes sure that you don't have to change all links in your application when changing the `basePath` value.

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/api-routes/response-helpers.md

@@ -25,3 +25,4 @@ The included helpers are:
 - `res.status(code)` - A function to set the status code. `code` must be a valid [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
 - `res.json(json)` - Sends a JSON response. `json` must be a valid JSON object
 - `res.send(body)` - Sends the HTTP response. `body` can be a `string`, an `object` or a `Buffer`
+- `res.redirect([status,] path)` - Redirects to a specified path or URL. `status` must be a valid [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). If not specified, `status` defaults to "302" "Found".

docs/manifest.json

@@ -227,6 +227,22 @@
               "title": "Environment Variables",
               "path": "/docs/api-reference/next.config.js/environment-variables.md"
             },
+            {
+              "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"