Merge branch 'canary' into response-helpers

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/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"

examples/custom-routes-proxying/package.json

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "next": "latest",
-    "react": "16.8.6",
-    "react-dom": "16.8.6"
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
   }
 }

examples/dynamic-routing/package.json

@@ -9,7 +9,7 @@
   "license": "ISC",
   "dependencies": {
     "next": "latest",
-    "react": "16.8.6",
-    "react-dom": "16.8.6"
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
   }
 }

examples/with-http2/package.json

@@ -8,8 +8,8 @@
   },
   "dependencies": {
     "next": "latest",
-    "react": "16.8.6",
-    "react-dom": "16.8.6"
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
   },
   "license": "ISC"
 }

examples/with-linaria/package.json

@@ -10,8 +10,8 @@
     "@zeit/next-css": "^1.0.1",
     "linaria": "2.0.0-alpha.5",
     "next": "latest",
-    "react": "16.8.3",
-    "react-dom": "16.8.3"
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
   },
   "license": "ISC"
 }

examples/with-rbx-bulma-pro/package.json

@@ -9,7 +9,7 @@
     "bulma-pro": "^0.1.7",
     "next": "^9.1.8-canary.11",
     "rbx": "^2.2.0",
-    "react": "16.8.6",
-    "react-dom": "16.8.6"
+    "react": "^16.13.1",
+    "react-dom": "^16.13.1"
   }
 }