Merge branch 'canary' into fix/9919-no-export-in-config

.eslintrc.json

@@ -61,6 +61,15 @@
             "ignoreRestSiblings": true
           }
         ],
+        "no-unused-expressions": "off",
+        "@typescript-eslint/no-unused-expressions": [
+          "error",
+          {
+            "allowShortCircuit": true,
+            "allowTernary": true,
+            "allowTaggedTemplates": true
+          }
+        ],
         "no-useless-constructor": "off",
         "@typescript-eslint/no-useless-constructor": "warn"
       }

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.config.js/runtime-configuration.md

@@ -28,7 +28,7 @@ Place any server-only runtime config under `serverRuntimeConfig`.
 
 Anything accessible to both client and server-side code should be under `publicRuntimeConfig`.
 
-> A page that relies on `publicRuntimeConfig` **must** use `getInitialProps` to opt-out of [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
+> A page that relies on `publicRuntimeConfig` **must** use `getInitialProps` to opt-out of [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md). Runtime configuration won't be available to any page (or component in a page) without `getInitialProps`.
 
 To get access to the runtime configs in your app use `next/config`, like so:
 

docs/api-reference/next/link.md

@@ -49,6 +49,8 @@ export default Home
 - [`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`
 
+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.
+
 ## Dynamic routes
 
 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:
@@ -72,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 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 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 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
@@ -92,7 +120,7 @@ const MyButton = React.forwardRef(({ onClick, href }, ref) => {
 
 function Home() {
   return (
-    <Link href="/about">
+    <Link href="/about" passHref>
       <MyButton />
     </Link>
   )
@@ -145,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/api-routes/introduction.md

@@ -46,6 +46,8 @@ export default (req, res) => {
 }
 ```
 
+To fetch API endpoints, take a look into any of the examples at the start of this section.
+
 > API Routes [do not specify CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), meaning they are **same-origin only** by default. You can customize such behavior by wrapping the request handler with [micro-cors](/docs/api-routes/api-middlewares.md#micro-support).
 
 > API Routes do not increase your client-side bundle size. They are server-side only bundles.

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

@@ -157,10 +157,22 @@ export default HelloWorld
 
 Please see the [styled-jsx documentation](https://github.com/zeit/styled-jsx) for more examples.
 
-## Sass, Less, and Stylus Support
+## Sass Support
 
-To support importing `.scss`, `.less` or `.styl` files you can use the following plugins:
+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:
 
-- [@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/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,
+  },
+}
+```