Merge branch 'canary' into patch-1

docs/advanced-features/customizing-postcss-config.md

@@ -26,13 +26,48 @@ Out of the box, with no configuration, Next.js compiles CSS with the following t
    - [Gap Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/gap)
    - [Media Query Ranges](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#Syntax_improvements_in_Level_4)
 
-By default, [Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/var) (CSS variables) are **not compiled** for IE11 support.
+By default, [CSS Grid](https://www.w3.org/TR/css-grid-1/) and [Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/var) (CSS variables) are **not compiled** for IE11 support.
+
+To compile [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid) for IE11, you can place the following comment at the top of your CSS file:
+
+```css
+/* autoprefixer grid: autoplace */
+```
+
+You can also enable IE11 support for [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid)
+in your entire project by configuring autoprefixer with the configuration shown below (collapsed).
+See ["Customizing Plugins"](#customizing-plugins) below for more information.
+
+<details>
+<summary><strong>Click to view the configuration to enable CSS Grid Layout</strong></summary>
+
+```json
+{
+  "plugins": [
+    "postcss-flexbugs-fixes",
+    [
+      "postcss-preset-env",
+      {
+        "autoprefixer": {
+          "flexbox": "no-2009",
+          "grid": "autoplace"
+        },
+        "stage": 3,
+        "features": {
+          "custom-properties": false
+        }
+      }
+    ]
+  ]
+}
+```
+
+</details>
+<br/>
 
 CSS variables are not compiled because it is [not possible to safely do so](https://github.com/MadLittleMods/postcss-css-variables#caveats).
 If you must use variables, consider using something like [Sass variables](https://sass-lang.com/documentation/variables) which are compiled away by [Sass](https://sass-lang.com/).
 
-> **Note**: To support [Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid), you need to enable `grid: "autoplace"` for Autoprefixer. See ["Customizing Plugins"](#customizing-plugins) below.
-
 ## Customizing Target Browsers
 
 Next.js allows you to configure the target browsers (for [Autoprefixer](https://github.com/postcss/autoprefixer) and compiled css features) through [Browserslist](https://github.com/browserslist/browserslist).

docs/advanced-features/dynamic-import.md

@@ -4,17 +4,49 @@ description: Dynamically import JavaScript modules and React Components and spli
 
 # Dynamic Import
 
-<details>
+<details open>
   <summary><b>Examples</b></summary>
   <ul>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-dynamic-import">Dynamic Import</a></li>
   </ul>
 </details>
 
-Next.js supports ES2020 [dynamic `import()`](https://github.com/tc39/proposal-dynamic-import) for JavaScript. With it you can import JavaScript modules (inc. React Components) dynamically and work with them. They also work with SSR.
+Next.js supports ES2020 [dynamic `import()`](https://github.com/tc39/proposal-dynamic-import) for JavaScript. With it you can import JavaScript modules dynamically and work with them. They also work with SSR.
+
+In the following example, we implement fuzzy search using `fuse.js` and only load the module dynamically in the browser after the user types in the search input:
+
+```jsx
+import { useState } from 'react'
+
+const names = ['Tim', 'Joe', 'Bel', 'Max', 'Lee']
+
+export default function Page() {
+  const [results, setResults] = useState()
+
+  return (
+    <div>
+      <input
+        type="text"
+        placeholder="Search"
+        onChange={async (e) => {
+          const { value } = e.currentTarget
+          // Dynamically load fuse.js
+          const Fuse = (await import('fuse.js')).default
+          const fuse = new Fuse(names)
+
+          setResults(fuse.search(value))
+        }}
+      />
+      <pre>Results: {JSON.stringify(results, null, 2)}</pre>
+    </div>
+  )
+}
+```
 
 You can think of dynamic imports as another way to split your code into manageable chunks.
 
+React components can also be imported using dynamic imports, but in this case we use it in conjunction with `next/dynamic` to make sure it works just like any other React Component. Check out the sections below for more details on how it works.
+
 ## Basic usage
 
 In the following example, the module `../components/hello` will be dynamically loaded by the page:

docs/advanced-features/measuring-performance.md

@@ -160,13 +160,12 @@ export function reportWebVitals(metric) {
 > export function reportWebVitals({ id, name, label, value }) {
 >   // Use `window.gtag` if you initialized Google Analytics as this example:
 >   // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_document.js
->   window.gtag('send', 'event', {
->     eventCategory:
+>   window.gtag('event', name, {
+>     event_category:
 >       label === 'web-vital' ? 'Web Vitals' : 'Next.js custom metric',
->     eventAction: name,
->     eventValue: Math.round(name === 'CLS' ? value * 1000 : value), // values must be integers
->     eventLabel: id, // id unique to current page load
->     nonInteraction: true, // avoids affecting bounce rate.
+>     value: Math.round(name === 'CLS' ? value * 1000 : value), // values must be integers
+>     event_label: id, // id unique to current page load
+>     non_interaction: true, // avoids affecting bounce rate.
 >   })
 > }
 > ```

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

@@ -6,11 +6,9 @@ description: Learn more about setting a base path in Next.js
 
 > This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5) and up. If you’re using older versions of Next.js, please upgrade before trying it out.
 
-To deploy a Next.js application under a sub-path of a domain you can use the `basePath` option.
+To deploy a Next.js application under a sub-path of a domain you can use the `basePath` config 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`:
+`basePath` allows you to set a path prefix for the application. For example, to use `/docs` instead of `/` (the default), open `next.config.js` and add the `basePath` config:
 
 ```js
 module.exports = {

docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md

@@ -4,6 +4,13 @@ description: A custom asset prefix allows you serve static assets from a CDN. Le
 
 # CDN Support with Asset Prefix
 
+> **Attention**: [Deploying to Vercel](docs/deployment.md) automatically configures a global CDN for your Next.js project.
+> You do not need to manually setup an Asset Prefix.
+
+> **Note**: Next.js 9.5+ added support for a customizable [Base Path](docs/api-reference/next.config.js/basepath.md), which is better
+> suited for hosting your application on a sub-path like `/docs`.
+> We do not suggest you use a custom Asset Prefix for this use case.
+
 To set up a [CDN](https://en.wikipedia.org/wiki/Content_delivery_network), you can set up an asset prefix and configure your CDN's origin to resolve to the domain that Next.js is hosted on.
 
 Open `next.config.js` and add the `assetPrefix` config:
@@ -17,7 +24,13 @@ module.exports = {
 }
 ```
 
-Next.js will automatically use your prefix in the scripts it loads, but this has no effect whatsoever on the [public](/docs/basic-features/static-file-serving.md) folder; if you want to serve those assets over a CDN, you'll have to introduce the prefix yourself. One way of introducing a prefix that works inside your components and varies by environment is documented [in this example](https://github.com/vercel/next.js/tree/canary/examples/with-universal-configuration-build-time).
+Next.js will automatically use your asset prefix for the JavaScript and CSS files it loads from the `/_next/` path (`.next/static/` folder).
+
+Asset prefix support does not influence the following paths:
+
+- Files in the [public](/docs/basic-features/static-file-serving.md) folder; if you want to serve those assets over a CDN, you'll have to introduce the prefix yourself
+- `/_next/data/` requests for `getServerSideProps` pages. These requests will always be made against the main domain since they're not static.
+- `/_next/data/` requests for `getStaticProps` pages. These requests will always be made against the main domain to support [Incremental Static Generation](/docs/basic-features/data-fetching.md#incremental-static-regeneration), even if you're not using it (for consistency).
 
 ## Related
 

docs/api-reference/next.config.js/runtime-configuration.md

@@ -4,7 +4,7 @@ description: Add client and server runtime configuration to your Next.js app.
 
 # Runtime Configuration
 
-> Generally you'll want to use [build-time environment variables](/docs/api-reference/next.config.js/environment-variables.md) to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
+> Generally you'll want to use [build-time environment variables](/docs/basic-features/environment-variables.md) to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
 
 To add runtime configuration to your app open `next.config.js` and add the `publicRuntimeConfig` and `serverRuntimeConfig` configs:
 

docs/api-reference/next/link.md

@@ -16,7 +16,13 @@ description: Enable client-side transitions between routes with the built-in Lin
 
 Client-side transitions between routes can be enabled via the `Link` component exported by `next/link`.
 
-An example of linking to `/` and `/about`:
+For an example, consider a `pages` directory with the following files:
+
+- `pages/index.js`
+- `pages/about.js`
+- `pages/blog/[slug].js`
+
+We can have a link to each of these pages like so:
 
 ```jsx
 import Link from 'next/link'
@@ -34,6 +40,11 @@ function Home() {
           <a>About Us</a>
         </Link>
       </li>
+      <li>
+        <Link href="/blog/hello-world">
+          <a>Blog Post</a>
+        </Link>
+      </li>
     </ul>
   )
 }
@@ -43,37 +54,38 @@ export default Home
 
 `Link` accepts the following props:
 
-- `href` - The path inside `pages` directory. This is the only required prop
-- `as` - The path that will be rendered in the browser URL bar. Used for dynamic routes
+- `href` - The path or URL to navigate to. This is the only required prop
+- `as` - Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked
 - [`passHref`](#if-the-child-is-a-custom-component-that-wraps-an-a-tag) - Forces `Link` to send the `href` property to its child. Defaults to `false`
-- `prefetch` - Prefetch the page in the background. Defaults to `true`. Any `<Link />` that is in the viewport (initially or through scroll) will be preloaded. Pages using [Static Generation](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) will preload `JSON` files with the data for faster page transitions.
+- `prefetch` - Prefetch the page in the background. Defaults to `true`. Any `<Link />` that is in the viewport (initially or through scroll) will be preloaded. Pages using [Static Generation](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) will preload `JSON` files with the data for faster page transitions
 - [`replace`](#replace-the-url-instead-of-push) - Replace the current `history` state instead of adding a new url into the stack. Defaults to `false`
 - [`scroll`](#disable-scrolling-to-the-top-of-the-page) - Scroll to the top of the page after a navigation. Defaults to `true`
 - [`shallow`](/docs/routing/shallow-routing.md) - Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation), [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) or [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md). Defaults to `false`
 
-External URLs, and any links that don't require a route navigation using `/pages`, don't need to be handled with `Link`; use the anchor tag for such cases instead.
+## If the route has dynamic segments
 
-## Dynamic routes
+There is nothing special to do when linking to a [dynamic route](/docs/routing/dynamic-routes.md), including [catch all routes](/docs/routing/dynamic-routes.md#catch-all-routes), since Next.js 9.5.3 (for older versions check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes)). However, it can become quite common and handy to use [interpolation](/docs/routing/introduction.md#linking-to-dynamic-paths) or an [URL Object](#with-url-object) to generate the link.
 
-A `Link` to a dynamic route is a combination of the `href` and `as` props. A link to the page `pages/post/[pid].js` will look like this:
+For example, the dynamic route `pages/blog/[slug].js` will match the following link:
 
 ```jsx
-<Link href="/post/[pid]" as="/post/abc">
-  <a>First Post</a>
-</Link>
-```
-
-`href` is a file system path used by the page and it shouldn't change at runtime. `as` on the other hand, will be dynamic most of the time according to your needs. Here's an example of how to create a list of links:
+import Link from 'next/link'
 
-```jsx
-const pids = ['id1', 'id2', 'id3']
-{
-  pids.map((pid) => (
-    <Link href="/post/[pid]" as={`/post/${pid}`}>
-      <a>Post {pid}</a>
-    </Link>
-  ))
+function Posts({ posts }) {
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>
+          <Link href={`/blog/${encodeURIComponent(post.slug)}`}>
+            <a>{post.title}</a>
+          </Link>
+        </li>
+      ))}
+    </ul>
+  )
 }
+
+export default Posts
 ```
 
 ## If the child is a custom component that wraps an `<a>` tag
@@ -140,18 +152,40 @@ import Link from 'next/link'
 
 function Home() {
   return (
-    <div>
-      <Link href={{ pathname: '/about', query: { name: 'test' } }}>
-        <a>About us</a>
-      </Link>
-    </div>
+    <ul>
+      <li>
+        <Link
+          href={{
+            pathname: '/about',
+            query: { name: 'test' },
+          }}
+        >
+          <a>About us</a>
+        </Link>
+      </li>
+      <li>
+        <Link
+          href={{
+            pathname: '/blog/[slug]',
+            query: { slug: 'my-post' },
+          }}
+        >
+          <a>Blog Post</a>
+        </Link>
+      </li>
+    </ul>
   )
 }
 
 export default Home
 ```
 
-The above example will be a link to `/about?name=test`. You can use every property as defined in the [Node.js URL module documentation](https://nodejs.org/api/url.html#url_url_strings_and_url_objects).
+The above example has a link to:
+
+- A predefined route: `/about?name=test`
+- A [dynamic route](/docs/routing/dynamic-routes.md): `/blog/my-post`
+
+You can use every property as defined in the [Node.js URL module documentation](https://nodejs.org/api/url.html#url_url_strings_and_url_objects).
 
 ## Replace the URL instead of push
 

docs/api-reference/next/router.md

@@ -62,8 +62,8 @@ Handles client-side transitions, this method is useful for cases where [`next/li
 router.push(url, as, options)
 ```
 
-- `url` - The URL to navigate to. This is usually the name of a `page`
-- `as` - Optional decorator for the URL that will be shown in the browser. Defaults to `url`
+- `url` - The URL to navigate to
+- `as` - Optional decorator for the URL that will be shown in the browser. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked
 - `options` - Optional object with the following configuration options:
   - [`shallow`](/docs/routing/shallow-routing.md): Update the path of the current page without rerunning [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation), [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) or [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md). Defaults to `false`
 
@@ -91,11 +91,7 @@ import { useRouter } from 'next/router'
 export default function Page() {
   const router = useRouter()
 
-  return (
-    <span onClick={() => router.push('/post/[pid]', '/post/abc')}>
-      Click me
-    </span>
-  )
+  return <span onClick={() => router.push('/post/abc')}>Click me</span>
 }
 ```
 
@@ -129,15 +125,15 @@ You can use an URL object in the same way you can use it for [`next/link`](/docs
 ```jsx
 import { useRouter } from 'next/router'
 
-export default function ReadMore() {
+export default function ReadMore({ post }) {
   const router = useRouter()
 
   return (
     <span
       onClick={() => {
         router.push({
-          pathname: '/about',
-          query: { name: 'Vercel' },
+          pathname: '/post/[pid]',
+          query: { pid: post.id },
         })
       }}
     >
@@ -181,8 +177,8 @@ Prefetch pages for faster client-side transitions. This method is only useful fo
 router.prefetch(url, as)
 ```
 
-- `url` - The path to a `page` inside the `pages` directory
-- `as` - Optional decorator for `url`, used to prefetch [dynamic routes](/docs/routing/dynamic-routes.md). Defaults to `url`
+- `url` - The URL to prefetch, that is, a path with a matching page
+- `as` - Optional decorator for `url`. Before Next.js 9.5.3 this was used to prefetch dynamic routes, check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes) to see how it worked
 
 #### Usage
 
@@ -210,7 +206,7 @@ export default function Login() {
   }, [])
 
   useEffect(() => {
-    // Prefetch the dashboard page as the user will go there after the login
+    // Prefetch the dashboard page
     router.prefetch('/dashboard')
   }, [])
 
@@ -317,9 +313,7 @@ You can listen to different events happening inside the Next.js Router. Here's a
 - `hashChangeStart(url)` - Fires when the hash will change but not the page
 - `hashChangeComplete(url)` - Fires when the hash has changed but not the page
 
-> Here `url` is the URL shown in the browser. If you call `router.push(url, as)` (or similar), then the value of `url` will be `as`.
->
-> **Note:** If you [configure a `basePath`](/docs/api-reference/next.config.js/basepath.md) then the value of `url` will be `basePath + as`.
+> **Note:** Here `url` is the URL shown in the browser, including the [`basePath`](/docs/api-reference/next.config.js/basepath.md).
 
 #### Usage