Merge branch 'canary' into patch/7980

azure-pipelines.yml

@@ -62,5 +62,5 @@ jobs:
         displayName: 'Install dependencies'
 
       - script: |
-          node run-tests.js -g $(group)
+          node run-tests.js -g $(group) --timings
         displayName: 'Run tests'

docs/advanced-features/custom-server.md

@@ -11,7 +11,7 @@ description: Start a Next.js app programmatically using a custom server.
     <li><a href="https://github.com/zeit/next.js/tree/canary/examples/custom-server-express">Express integration</a></li>
     <li><a href="https://github.com/zeit/next.js/tree/canary/examples/custom-server-hapi">Hapi integration</a></li>
     <li><a href="https://github.com/zeit/next.js/tree/canary/examples/custom-server-koa">Koa integration</a></li>
-    <li><a href="https://github.com/zeit/next.js/tree/canary/examples/ssr-caching">SSR Catching</a></li>
+    <li><a href="https://github.com/zeit/next.js/tree/canary/examples/ssr-caching">SSR Caching</a></li>
   </ul>
 </details>
 

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

@@ -0,0 +1,134 @@
+---
+description: Extend the PostCSS config and plugins added by Next.js with your own.
+---
+
+# Customizing PostCSS Config
+
+<details open>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/zeit/next.js/tree/canary/examples/with-tailwindcss">Tailwind CSS Example</a></li>
+  </ul>
+</details>
+
+## Default Behavior
+
+Next.js compiles CSS for its [built-in CSS support](/docs/basic-features/built-in-css-support) using PostCSS.
+
+Out of the box, with no configuration, Next.js compiles CSS with the following transformations:
+
+1. [Autoprefixer](https://github.com/postcss/autoprefixer) automatically adds vendor prefixes to CSS rules (back to IE11).
+1. [Cross-browser Flexbox bugs](https://github.com/philipwalton/flexbugs) are corrected to behave like [the spec](https://www.w3.org/TR/css-flexbox-1/).
+1. New CSS features are automatically compiled for Internet Explorer 11 compatibility:
+   - [`all` Property](https://developer.mozilla.org/en-US/docs/Web/CSS/all)
+   - [Break Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/break-after)
+   - [`font-variant` Property](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
+   - [Gap Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/gap)
+   - [Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/grid)
+   - [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.
+
+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/).
+
+## 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).
+
+To customize browserslist, create a `browserslist` key in your `package.json` like so:
+
+```json
+{
+  "browserslist": [">0.3%", "not ie 11", "not dead", "not op_mini all"]
+}
+```
+
+You can use the [browserl.ist](https://browserl.ist/?q=%3E0.3%25%2C+not+ie+11%2C+not+dead%2C+not+op_mini+all) tool to visualize what browsers you are targeting.
+
+## CSS Modules
+
+No configuration is needed to support CSS Modules. To enable CSS Modules for a file, rename the file to have the extension `.module.css`.
+
+You can learn more about [Next.js' CSS Module support here](/docs/basic-features/built-in-css-support).
+
+## Customizing Plugins
+
+> **Warning**: When you define a custom PostCSS configuration file, Next.js **completely disables** the defaults listed above.
+> Be sure to manually configure all features you need compiled, including [Autoprefixer](https://github.com/postcss/autoprefixer).
+
+To customize the PostCSS configuration, create a `postcss.config.json` file in the root of your project.
+
+This is the default configuration used by Next.js:
+
+```json
+{
+  "plugins": [
+    "postcss-flexbugs-fixes",
+    [
+      "postcss-preset-env",
+      {
+        "autoprefixer": {
+          "flexbox": "no-2009"
+        },
+        "stage": 3,
+        "features": {
+          "custom-properties": false
+        }
+      }
+    ]
+  ]
+}
+```
+
+> **Note**: Next.js also allows the file to be named `.postcssrc.json`, or, to be read from the `postcss` key in `package.json`.
+
+It is also possible to configure PostCSS with a `postcss.config.js` file, which is useful when you want to conditionally include plugins based on environment:
+
+```js
+module.exports = {
+  plugins:
+    process.env.NODE_ENV === 'production'
+      ? [
+          'postcss-flexbugs-fixes',
+          [
+            'postcss-preset-env',
+            {
+              autoprefixer: {
+                flexbox: 'no-2009',
+              },
+              stage: 3,
+              features: {
+                'custom-properties': false,
+              },
+            },
+          ],
+        ]
+      : [
+          // No transformations in development
+        ],
+}
+```
+
+Do **not use `require()`** to import the PostCSS Plugins. Plugins must be provided as strings.
+
+> **Note**: Next.js also allows the file to be named `.postcssrc.js`.
+
+> **Note**: If your `postcss.config.js` needs to support other non-Next.js tools in the same project, you must use the interoperable object-based format instead:
+>
+> ```js
+> module.exports = {
+>   plugins: {
+>     'postcss-flexbugs-fixes': {},
+>     'postcss-preset-env': {
+>       autoprefixer: {
+>         flexbox: 'no-2009',
+>       },
+>       stage: 3,
+>       features: {
+>         'custom-properties': false,
+>       },
+>     },
+>   },
+> }
+> ```

docs/api-reference/next/link.md

@@ -74,12 +74,38 @@ const pids = ['id1', 'id2', 'id3']
 }
 ```
 
-## Example with `React.forwardRef`
+## If the child is a custom component that wraps an `<a>` tag
 
-If the child component in `Link` is a function component, you'll need to wrap it in [`React.forwardRef`](https://reactjs.org/docs/react-api.html#reactforwardref) like in the following example:
+If the child of `Link` is a custom component that wraps an `<a>` tag, you must add `passHref` to `Link`. This is necessary if you’re using libraries like [styled-components](https://styled-components.com/). Without this, the `<a>` tag will not have the `href` attribute, which might hurt your site’s SEO.
+
+```jsx
+import Link from 'next/link'
+import styled from 'styled-components'
+
+// This creates a custom component that wraps an <a> tag
+const RedLink = styled.a`
+  color: red;
+`
+
+function NavLink({ href, name }) {
+  // Must add passHref to Link
+  return (
+    <Link href={href} passHref>
+      <RedLink>{name}</RedLink>
+    </Link>
+  )
+}
+
+export default NavLink
+```
+
+> **Note:** If you’re using [emotion](https://emotion.sh/)’s JSX pragma feature (`@jsx jsx`), you must use `passHref` even if you use an `<a>` tag directly.
+
+## If the child is a function component
+
+If the child of `Link` is a function component, in addition to using `passHref`, you must wrap the component in [`React.forwardRef`](https://reactjs.org/docs/react-api.html#reactforwardref):
 
 ```jsx
-import React from 'react'
 import Link from 'next/link'
 
 // `onClick`, `href`, and `ref` need to be passed to the DOM element
@@ -94,7 +120,7 @@ const MyButton = React.forwardRef(({ onClick, href }, ref) => {
 
 function Home() {
   return (
-    <Link href="/about">
+    <Link href="/about" passHref>
       <MyButton />
     </Link>
   )
@@ -147,29 +173,6 @@ The default behavior of the `Link` component is to `push` a new URL into the `hi
 
 The child of `Link` is `<img>` instead of `<a>`. `Link` will send the `onClick` property to `<img>` but won't pass the `href` property.
 
-## Forcing `Link` to expose `href` to its child
-
-If the child is an `<a>` tag and doesn't have a `href` attribute we specify it so that the repetition is not needed by the user. However, sometimes, you’ll want to pass an `<a>` tag inside of a wrapper and `Link` won’t recognize it as a _hyperlink_, and, consequently, won’t transfer its `href` to the child.
-
-In cases like that, you can add the `passHref` property to `Link`, forcing it to expose its `href` property to the child. Take a look at the following example:
-
-```jsx
-import Link from 'next/link'
-import Unexpected_A from 'third-library'
-
-function NavLink({ href, name }) {
-  return (
-    <Link href={href} passHref>
-      <Unexpected_A>{name}</Unexpected_A>
-    </Link>
-  )
-}
-
-export default NavLink
-```
-
-> **Please note**: using a tag other than `<a>` and failing to pass `passHref` may result in links that appear to navigate correctly, but, when being crawled by search engines, will not be recognized as links (owing to the lack of `href` attribute). This may result in negative effects on your sites SEO.
-
 ## Disable scrolling to the top of the page
 
 The default behavior of `Link` is to scroll to the top of the page. When there is a hash defined it will scroll to the specific id, just like a normal `<a>` tag. To prevent scrolling to the top / hash `scroll={false}` can be added to `Link`:

docs/basic-features/built-in-css-support.md

@@ -157,22 +157,10 @@ export default HelloWorld
 
 Please see the [styled-jsx documentation](https://github.com/zeit/styled-jsx) for more examples.
 
-## Sass Support
+## Sass, Less and Stylus Support
 
-Next.js allows you to import Sass using both the `.scss` and `.sass` extensions.
-You can use component-level Sass via CSS Modules and the `.module.scss` or `.module.sass` extension.
-
-Before you can use Next.js' built-in Sass support, be sure to install [`sass`](https://github.com/sass/sass):
-
-```bash
-npm install sass
-```
-
-Sass support has the same benefits and restrictions as the built-in CSS support detailed above.
-
-## Less and Stylus Support
-
-To support importing `.less` or `.styl` files you can use the following plugins:
+To support importing `.scss`, `.sass`, `.less`, or `.styl` files you can use the following plugins:
 
+- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
 - [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
 - [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus)

docs/basic-features/typescript.md

@@ -101,7 +101,7 @@ The following is an example of how to use the built-in types for API routes:
 import { NextApiRequest, NextApiResponse } from 'next'
 
 export default (req: NextApiRequest, res: NextApiResponse) => {
-  res.status(200).json({ name: 'Jhon Doe' })
+  res.status(200).json({ name: 'John Doe' })
 }
 ```
 
@@ -115,6 +115,6 @@ type Data = {
 }
 
 export default (req: NextApiRequest, res: NextApiResponse<Data>) => {
-  res.status(200).json({ name: 'Jhon Doe' })
+  res.status(200).json({ name: 'John Doe' })
 }
 ```

docs/getting-started.md

@@ -39,7 +39,7 @@ These scripts refer to the different stages of developing an application:
 - `build` - Runs `next build` which builds the application for production usage
 - `start` - Runs `next start` which starts a Next.js production server
 
-Next.js is built around the concept of pages. A page is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.ts`, or `.tsx` file in the `pages` directory.
+Next.js is built around the concept of pages. A page is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.jsx`, `.ts`, or `.tsx` file in the `pages` directory.
 
 Pages are associated with a route based on their file name. For example `pages/about.js` is mapped to `/about`. You can even add dynamic route parameters with the filename.
 

docs/manifest.json

@@ -121,6 +121,10 @@
               "title": "Customizing Babel Config",
               "path": "/docs/advanced-features/customizing-babel-config.md"
             },
+            {
+              "title": "Customizing PostCSS Config",
+              "path": "/docs/advanced-features/customizing-postcss-config.md"
+            },
             {
               "title": "Custom Server",
               "path": "/docs/advanced-features/custom-server.md"

docs/routing/dynamic-routes.md

@@ -60,7 +60,7 @@ Client-side navigations to a dynamic route can be handled with [`next/link`](/do
 
 Dynamic routes can be extended to catch all paths by adding three dots (`...`) inside the brackets. For example:
 
-- `pages/post/[...slug]` matches `/post/a`, but also `post/a/b`, `post/a/b/c` and so on.
+- `pages/post/[...slug].js` matches `/post/a`, but also `post/a/b`, `post/a/b/c` and so on.
 
 Matched parameters will be sent as a query parameter (`slug` in the example) to the page, and it will always be an array, so, the path `/post/a` will have the following `query` object:
 

docs/routing/introduction.md

@@ -30,7 +30,7 @@ To match a dynamic segment you can use the bracket syntax. This allows you to ma
 
 - `pages/blog/[slug].js` → `/blog/:slug` (`/blog/hello-world`)
 - `pages/[username]/settings.js` → `/:username/settings` (`/foo/settings`)
-- `pages/post/[...all]` → `/post/*` (`/post/2020/id/title`)
+- `pages/post/[...all].js` → `/post/*` (`/post/2020/id/title`)
 
 ## Linking between pages
 

errors/no-cache.md

@@ -74,3 +74,34 @@ cache:
     - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i`
     - '.next/cache/**/*' # Cache Next.js for faster application rebuilds
 ```
+
+**GitHub Actions**
+
+Using GitHub's [actions/cache](https://github.com/actions/cache), add the following step in your workflow file:
+
+```yaml
+uses: actions/cache@v1
+with:
+  path: ${{ github.workspace }}/.next/cache
+  key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}
+```
+
+**Bitbucket Pipelines**
+
+Add or merge the following into your `bitbucket-pipelines.yml` at the top level (same level as `pipelines`):
+
+```yaml
+definitions:
+  caches:
+    nextcache: .next/cache
+```
+
+Then reference it in the `caches` section of your pipeline's `step`:
+
+```yaml
+- step:
+    name: your_step_name
+    caches:
+      - node
+      - nextcache
+```

errors/postcss-function.md

@@ -0,0 +1,30 @@
+# PostCSS Configuration Is a Function
+
+#### Why This Error Occurred
+
+The project's custom PostCSS configuration exports a function instead of an object.
+
+#### Possible Ways to Fix It
+
+Adjust the custom PostCSS configuration to not export a function.
+Instead, return a plain object—if you need environment information, read it from `process.env`.
+
+**Before**
+
+```js
+module.exports = ({ env }) => ({
+  plugins: {
+    'postcss-plugin': env === 'production' ? {} : false,
+  },
+})
+```
+
+**After**
+
+```js
+module.exports = {
+  plugins: {
+    'postcss-plugin': process.env.NODE_ENV === 'production' ? {} : false,
+  },
+}
+```

errors/postcss-ignored-plugin.md

@@ -0,0 +1,20 @@
+# Ignored PostCSS Plugin
+
+#### Why This Error Occurred
+
+The project's custom PostCSS configuration attempts to configure unnecessary plugins:
+
+- postcss-modules-values
+- postcss-modules-scope
+- postcss-modules-extract-imports
+- postcss-modules-local-by-default
+- postcss-modules
+
+#### Possible Ways to Fix It
+
+Remove the plugin specified in the error message from your custom PostCSS configuration.
+
+#### How do I configure CSS Modules?
+
+CSS Modules are supported in [Next.js' built-in CSS support](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+You can [read more](https://nextjs.org/docs/advanced-features/customizing-postcss-config) about how to use them [here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).