Merge branch 'canary' into feature/storybook-default-import

vercel · Dec 18, 2020 · 641e3be · 641e3be
2 parents 8052b05 + 121e88d
commit 641e3be
Show file tree

Hide file tree

Showing 391 changed files with 9,488 additions and 4,072 deletions.
diff --git a/.github/ISSUE_TEMPLATE/1.Bug_report.md b/.github/ISSUE_TEMPLATE/1.Bug_report.md
@@ -33,8 +33,9 @@ If applicable, add screenshots to help explain your problem.
 
 - OS: [e.g. macOS, Windows]
 - Browser (if applies) [e.g. chrome, safari]
-- Version of Next.js: [e.g. 6.0.2]
-- Version of Node.js: [e.g. 10.10.0]
+- Version of Next.js: [e.g. 10.0.1]
+- Version of Node.js: [e.g. 12.0.0]
+- Deployment: [e.g. next start, next export, Vercel, other platform]
 
 ## Additional context
 

diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml
@@ -0,0 +1,17 @@
+name: Cancel
+on:
+  pull_request_target:
+    types:
+      - edited
+      - synchronize
+
+jobs:
+  cancel:
+    name: 'Cancel Previous Runs'
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - uses: styfle/[email protected]
+        with:
+          workflow_id: 444921, 444987
+          access_token: ${{ github.token }}
diff --git a/docs/advanced-features/dynamic-import.md b/docs/advanced-features/dynamic-import.md
@@ -71,6 +71,8 @@ export default Home
 
 `DynamicComponent` will be the default component returned by `../components/hello`. It works like a regular React Component, and you can pass props to it as you normally would.
 
+> **Note**: `import()` needs to be explicitly written without template strings. Furthermore the `import()` has to be inside the `dynamic()` call for Next.js to be able to match webpack bundles / module ids to the specific `dynamic()` call and preload them before rendering. `dynamic()` can't be used inside of React rendering as it needs to be marked in the top level of the module for preloading to work, similar to `React.lazy`.
+
 ## With named exports
 
 If the dynamic component is not the default export, you can use a named export too. Consider the module `../components/hello.js` which has a named export `Hello`:

diff --git a/docs/advanced-features/i18n-routing.md b/docs/advanced-features/i18n-routing.md
@@ -152,13 +152,13 @@ When `localeDetection` is set to `false` Next.js will no longer automatically re
 
 ## Accessing the locale information
 
-You can access the locale information via the Next.js router. For example, using the [`useRouter()`](https://nextjs.org/docs/api-reference/next/router#userouter) hook the following properties are available:
+You can access the locale information via the Next.js router. For example, using the [`useRouter()`](/docs/api-reference/next/router.md#userouter) hook the following properties are available:
 
 - `locale` contains the currently active locale.
 - `locales` contains all configured locales.
 - `defaultLocale` contains the configured default locale.
 
-When [pre-rendering](/docs/basic-features/pages#static-generation-recommended) pages with `getStaticProps` or `getServerSideProps`, the locale information is provided in [the context](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) provided to the function.
+When [pre-rendering](/docs/basic-features/pages.md#static-generation-recommended) pages with `getStaticProps` or `getServerSideProps`, the locale information is provided in [the context](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) provided to the function.
 
 When leveraging `getStaticPaths`, the configured locales are provided in the context parameter of the function under `locales` and the configured defaultLocale under `defaultLocale`.
 
@@ -214,6 +214,12 @@ export default function IndexPage(props) {
 }
 ```
 
+## Leveraging the NEXT_LOCALE cookie
+
+Next.js supports overriding the accept-language header with a `NEXT_LOCALE=the-locale` cookie. This cookie can be set using a language switcher and then when a user comes back to the site it will leverage the locale specified in the cookie.
+
+For example, if a user prefers the locale `fr` but a `NEXT_LOCALE=en` cookie is set the `en` locale will be used instead until the cookie is removed or expired.
+
 ## Search Engine Optimization
 
 Since Next.js knows what language the user is visiting it will automatically add the `lang` attribute to the `<html>` tag.
@@ -222,9 +228,11 @@ Next.js doesn't know about variants of a page so it's up to you to add the `href
 
 ## How does this work with Static Generation?
 
+> Note that Internationalized Routing does not integrate with [`next export`](/docs/advanced-features/static-html-export.md) as `next export` does not leverage the Next.js routing layer. Hybrid Next.js applications that do not use `next export` are fully supported.
+
 ### Automatically Statically Optimized Pages
 
-For pages that are automatically statically optimized, a version of the page will be generated for each locale.
+For pages that are [automatically statically optimized](/docs/advanced-features/automatic-static-optimization.md), a version of the page will be generated for each locale.
 
 ### Non-dynamic getStaticProps Pages
 
@@ -255,7 +263,7 @@ export async function getStaticProps({ locale }) {
 
 ### Dynamic getStaticProps Pages
 
-For dynamic `getStaticProps` pages, any locale variants of the page that is desired to be prerendered needs to be returned from [`getStaticPaths`](/docs/basic-features/data-fetching#getstaticpaths-static-generation). Along with the `params` object that can be returned for the `paths`, you can also return a `locale` field specifying which locale you want to render. For example:
+For dynamic `getStaticProps` pages, any locale variants of the page that is desired to be prerendered needs to be returned from [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation). Along with the `params` object that can be returned for the `paths`, you can also return a `locale` field specifying which locale you want to render. For example:
 
 ```js
 // pages/blog/[slug].js

diff --git a/docs/advanced-features/source-maps.md b/docs/advanced-features/source-maps.md
@@ -0,0 +1,23 @@
+---
+description: Enables browser source map generation during the production build.
+---
+
+# Source Maps
+
+Source Maps are enabled by default during development. During production builds they are disabled as generation source maps can significantly increase build times and memory usage while being generated.
+
+Next.js provides a configuration flag you can use to enable browser source map generation during the production build:
+
+```js
+// next.config.js
+module.exports = {
+  productionBrowserSourceMaps: true,
+}
+```
+
+When the `productionBrowserSourceMaps` option is enabled the source maps will be output in the same directory as the JavaScript files, Next.js will automatically serve these files when requested.
+
+## Caveats
+
+- Can increase `next build` time
+- Increases memory usage during `next build`
diff --git a/docs/advanced-features/static-html-export.md b/docs/advanced-features/static-html-export.md
@@ -71,4 +71,5 @@ By default, `next export` will generate an `out` directory, which can be served
 - The [`fallback: true`](/docs/basic-features/data-fetching.md#fallback-true) mode of `getStaticPaths` is not supported when using `next export`.
 - [API Routes](/docs/api-routes/introduction.md) are not supported by this method because they can't be prerendered to HTML.
 - [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) cannot be used within pages because the method requires a server. Consider using [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) instead.
-- The [`next/image`](/docs/api-reference/next/image) component's default loader is not supported when using `next export`. However, other [loader](https://nextjs.org/docs/basic-features/image-optimization#loader) options will work.
+- [Internationalized Routing](/docs/advanced-features/i18n-routing.md) is not supported as it requires Next.js' server-side routing.
+- The [`next/image`](/docs/api-reference/next/image.md) component's default loader is not supported when using `next export`. However, other [loader](/docs/basic-features/image-optimization.md#loader) options will work.
diff --git a/docs/api-reference/data-fetching/getInitialProps.md b/docs/api-reference/data-fetching/getInitialProps.md
@@ -54,7 +54,7 @@ export default Page
 
 Data returned from `getInitialProps` is serialized when server rendering, similar to what [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) does. Make sure the returned object from `getInitialProps` is a plain `Object` and not using `Date`, `Map` or `Set`.
 
-For the initial page load, `getInitialProps` will run on the server only. `getInitialProps` will then run on the client when navigating to a different route via the [`next/link`](/docs/api-reference/next/link.md) component or by using [`next/router`](/docs/api-reference/next/router.md).
+For the initial page load, `getInitialProps` will run on the server only. `getInitialProps` will then run on the client when navigating to a different route via the [`next/link`](/docs/api-reference/next/link.md) component or by using [`next/router`](/docs/api-reference/next/router.md). However, if `getInitialProps` is used in a custom `_app.js`, and the page being navigated to implements `getServerSideProps`, then `getInitialProps` will run on the server.
 
 ## Context Object
 

diff --git a/docs/api-reference/next.config.js/headers.md b/docs/api-reference/next.config.js/headers.md
@@ -178,7 +178,7 @@ module.exports = {
 
 ### Headers with i18n support
 
-When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with headers each `source` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the header:
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with headers each `source` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the header. If `locale: false` is used you must prefix the `source` with a locale for it to be matched correctly.
 
 ```js
 module.exports = {
@@ -209,6 +209,17 @@ module.exports = {
           },
         ],
       },
+      {
+        // this matches '/' since `en` is the defaultLocale
+        source: '/en',
+        locale: false,
+        headers: [
+          {
+            key: 'x-hello',
+            value: 'world',
+          },
+        ],
+      },
     ]
   },
 }

diff --git a/docs/api-reference/next.config.js/introduction.md b/docs/api-reference/next.config.js/introduction.md
@@ -46,6 +46,6 @@ module.exports = (phase, { defaultConfig }) => {
 
 The commented lines are the place where you can put the configs allowed by `next.config.js`, which are defined [here](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/server/config.ts#L12-L63).
 
-However, none of the configs are required, and it's not necessary to understand what each config does, instead, search for the features you need to enable or modify in this section and they will show you what to do.
+However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.
 
 > Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack, Babel or TypeScript.
diff --git a/docs/api-reference/next.config.js/redirects.md b/docs/api-reference/next.config.js/redirects.md
@@ -77,15 +77,15 @@ module.exports = {
 
 ### Regex Path Matching
 
-To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/blog/:slug(\\d{1,})` will match `/blog/123` but not `/blog/abc`:
+To match a regex path you can wrap the regex in parenthesis after a parameter, for example `/post/:slug(\\d{1,})` will match `/post/123` but not `/post/abc`:
 
 ```js
 module.exports = {
   async redirects() {
     return [
       {
-        source: '/old-blog/:post(\\d{1,})',
-        destination: '/blog/:post', // Matched parameters can be used in the destination
+        source: '/post/:slug(\\d{1,})',
+        destination: '/news/:slug', // Matched parameters can be used in the destination
         permanent: false,
       },
     ]
@@ -122,7 +122,7 @@ module.exports = {
 
 ### Redirects with i18n support
 
-When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with redirects each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the redirect:
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with redirects each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the redirect. If `locale: false` is used you must prefix the `source` and `destination` with a locale for it to be matched correctly.
 
 ```js
 module.exports = {
@@ -145,6 +145,13 @@ module.exports = {
         locale: false,
         permanent: false,
       },
+      {
+        // this matches '/' since `en` is the defaultLocale
+        source: '/en',
+        destination: '/en/another',
+        locale: false,
+        permanent: false,
+      },
     ]
   },
 }

diff --git a/docs/api-reference/next.config.js/rewrites.md b/docs/api-reference/next.config.js/rewrites.md
@@ -166,7 +166,7 @@ module.exports = {
 
 ### Rewrites with i18n support
 
-When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with rewrites each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the rewrite:
+When leveraging [`i18n` support](/docs/advanced-features/i18n-routing.md) with rewrites each `source` and `destination` is automatically prefixed to handle the configured `locales` unless you add `locale: false` to the rewrite. If `locale: false` is used you must prefix the `source` and `destination` with a locale for it to be matched correctly.
 
 ```js
 module.exports = {
@@ -187,6 +187,12 @@ module.exports = {
         destination: '/nl/another',
         locale: false,
       },
+      {
+        // this matches '/' since `en` is the defaultLocale
+        source: '/en',
+        destination: '/en/another',
+        locale: false,
+      },
     ]
   },
 }

diff --git a/docs/api-reference/next/image.md b/docs/api-reference/next/image.md
@@ -93,7 +93,9 @@ Try it out:
 
 ### sizes
 
-A string mapping media queries to device sizes. Defaults to [Device Sizes](/docs/basic-features/image-optimization.md#device-sizes).
+A string mapping media queries to device sizes. Defaults to `100vw`.
+
+We recommend setting `sizes` when `layout="responsive"` and your image will not be the same width as the viewport.
 
 [Learn more](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes).
 

diff --git a/docs/api-reference/next/link.md b/docs/api-reference/next/link.md
@@ -57,7 +57,7 @@ export default Home
 - `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. Prefetch can be disabled by passing `prefetch={false}`. 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`
@@ -113,7 +113,8 @@ function NavLink({ href, name }) {
 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 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.
+- The component should support `onClick` property to trigger navigation correctly
 
 ## If the child is a function component
 
@@ -197,27 +198,6 @@ The default behavior of the `Link` component is to `push` a new URL into the `hi
 </Link>
 ```
 
-## Using a component that supports `onClick`
-
-`Link` supports any component that supports the `onClick` event, in the case you don't provide an `<a>` tag, consider the following example:
-
-```jsx
-import Link from 'next/link'
-import Image from 'next/image'
-
-function Avatar() {
-  return (
-    <Link href="/about">
-      <Image src="/me.png" alt="me" width="64" height="64" />
-    </Link>
-  )
-}
-
-export default Avatar
-```
-
-The child of `Link` is [`Image`](/docs/api-reference/next/image.md) instead of `<a>`. `Link` will send the `onClick` property to `Image` but won't pass the `href` property.
-
 ## 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, like a normal `<a>` tag. To prevent scrolling to the top / hash `scroll={false}` can be added to `Link`:

diff --git a/docs/api-reference/next/router.md b/docs/api-reference/next/router.md
@@ -44,8 +44,8 @@ The following is the definition of the `router` object returned by both [`useRou
 - `pathname`: `String` - Current route. That is the path of the page in `/pages`
 - `query`: `Object` - The query string parsed to an object. It will be an empty object during prerendering if the page doesn't have [data fetching requirements](/docs/basic-features/data-fetching.md). Defaults to `{}`
 - `asPath`: `String` - The path (including the query) shown in the browser without the configured `basePath` or `locale`.
-- `isFallback`: `boolean` - Whether the current page is in [fallback mode](/docs/basic-features/data-fetching#fallback-pages).
-- `basePath`: `String` - The active [basePath](/docs/api-reference/next.config.js/basepath) (if enabled).
+- `isFallback`: `boolean` - Whether the current page is in [fallback mode](/docs/basic-features/data-fetching.md#fallback-pages).
+- `basePath`: `String` - The active [basePath](/docs/api-reference/next.config.js/basepath.md) (if enabled).
 - `locale`: `String` - The active locale (if enabled).
 - `locales`: `String[]` - All supported locales (if enabled).
 - `defaultLocale`: `String` - The current default locale (if enabled).
@@ -310,13 +310,13 @@ export default function Page() {
 
 You can listen to different events happening inside the Next.js Router. Here's a list of supported events:
 
-- `routeChangeStart(url)` - Fires when a route starts to change
-- `routeChangeComplete(url)` - Fires when a route changed completely
-- `routeChangeError(err, url)` - Fires when there's an error when changing routes, or a route load is cancelled
+- `routeChangeStart(url, { shallow })` - Fires when a route starts to change
+- `routeChangeComplete(url, { shallow })` - Fires when a route changed completely
+- `routeChangeError(err, url, { shallow })` - Fires when there's an error when changing routes, or a route load is cancelled
   - `err.cancelled` - Indicates if the navigation was cancelled
-- `beforeHistoryChange(url)` - Fires just before changing the browser's history
-- `hashChangeStart(url)` - Fires when the hash will change but not the page
-- `hashChangeComplete(url)` - Fires when the hash has changed but not the page
+- `beforeHistoryChange(url, { shallow })` - Fires just before changing the browser's history
+- `hashChangeStart(url, { shallow })` - Fires when the hash will change but not the page
+- `hashChangeComplete(url, { shallow })` - Fires when the hash has changed but not the page
 
 > **Note:** Here `url` is the URL shown in the browser, including the [`basePath`](/docs/api-reference/next.config.js/basepath.md).
 
@@ -332,8 +332,12 @@ export default function MyApp({ Component, pageProps }) {
   const router = useRouter()
 
   useEffect(() => {
-    const handleRouteChange = (url) => {
-      console.log('App is changing to: ', url)
+    const handleRouteChange = (url, { shallow }) => {
+      console.log(
+        `App is changing to ${url} ${
+          shallow ? 'with' : 'without'
+        } shallow routing`
+      )
     }
 
     router.events.on('routeChangeStart', handleRouteChange)