Merge branch 'canary' into examples/catch-all-routing

.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

@@ -15,7 +15,8 @@ For example, consider the following stylesheet named `styles.css`:
 
 ```css
 body {
-  font-family: 'SF Pro Text', 'SF Pro Icons', system-ui;
+  font-family: 'SF Pro Text', 'SF Pro Icons', 'Helvetica Neue', 'Helvetica',
+    'Arial', sans-serif;
   padding: 20px 20px 60px;
   max-width: 680px;
   margin: 0 auto;
@@ -157,9 +158,9 @@ export default HelloWorld
 
 Please see the [styled-jsx documentation](https://github.com/zeit/styled-jsx) for more examples.
 
-## Sass, Less, and Stylus Support
+## Sass, Less and Stylus Support
 
-To support importing `.scss`, `.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)

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

@@ -20,7 +20,7 @@ The interactive course with quizzes will guide you through everything you need t
 Install `next`, `react` and `react-dom` in your project:
 
 ```bash
-npm install --save next react react-dom
+npm install next react react-dom
 ```
 
 Open `package.json` and add the following `scripts`:
@@ -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"

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
+```