Merge branch 'canary' into add-route-events-types

Author: LauraBeatris

.github/workflows/build_test_deploy.yml

@@ -78,9 +78,8 @@ jobs:
       - run: exit 0
 
   testMacOS:
-    name: macOS ( Basic, Production, Acceptance )
+    name: macOS (Basic, Production, Acceptance)
     runs-on: macos-latest
-    needs: build
     env:
       NEXT_TELEMETRY_DISABLED: 1
       NEXT_TEST_JOB: 1
@@ -90,7 +89,24 @@ jobs:
       - uses: actions/checkout@v2
       - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
       # Installing dependencies again since OS changed
-      - run: yarn install --frozen-lockfile --check-files
+      - run: yarn install --frozen-lockfile --check-files || yarn install --frozen-lockfile --check-files
+      - run: node run-tests.js test/integration/production/test/index.test.js
+      - run: node run-tests.js test/integration/basic/test/index.test.js
+      - run: node run-tests.js test/acceptance/*
+
+  testWebpack5:
+    name: webpack 5 (Basic, Production, Acceptance)
+    runs-on: ubuntu-latest
+    env:
+      NEXT_TELEMETRY_DISABLED: 1
+      NEXT_TEST_JOB: 1
+      HEADLESS: true
+
+    steps:
+      - uses: actions/checkout@v2
+      - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+      - run: cat package.json | jq '.resolutions.webpack = "^5.0.0-beta.22"' > package.json.tmp && mv package.json.tmp package.json
+      - run: yarn install --check-files
       - run: node run-tests.js test/integration/production/test/index.test.js
       - run: node run-tests.js test/integration/basic/test/index.test.js
       - run: node run-tests.js test/acceptance/*

docs/advanced-features/measuring-performance.md

@@ -30,8 +30,8 @@ The `metric` object returned to the function consists of a number of properties:
 
 - `id`: Unique identifier for the metric in the context of the current page load
 - `name`: Metric name
-- `startTime`: First recorded timestamp of the performance entry (if applicable)
-- `value`: Value, or duration, of performance entry
+- `startTime`: First recorded timestamp of the performance entry in [milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp) (if applicable)
+- `value`: Value, or duration in [milliseconds](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp), of the performance entry
 - `label`: Type of metric (`web-vital` or `custom`)
 
 There are two types of metrics that are tracked:

docs/advanced-features/multi-zones.md

@@ -3,7 +3,7 @@
 <details>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://github.com/examples/with-zones">With Zones</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-zones">With Zones</a></li>
   </ul>
 </details>
 

docs/api-reference/next.config.js/custom-webpack-config.md

@@ -4,12 +4,18 @@ description: Extend the default webpack config added by Next.js.
 
 # Custom Webpack Config
 
+Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case:
+
+- [CSS imports](/docs/basic-features/built-in-css-support#adding-a-global-stylesheet)
+- [CSS modules](/docs/basic-features/built-in-css-support#adding-component-level-css)
+- [Sass/SCSS imports](/docs/basic-features/built-in-css-support#sass-support)
+- [Sass/SCSS modules](/docs/basic-features/built-in-css-support#sass-support)
+- [preact](https://github.com/vercel/next.js/tree/canary/examples/using-preact)
+- [Customizing babel configuration](/docs/advanced-features/customizing-babel-config)
+
 Some commonly asked for features are available as 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)
-- [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact)
+- [@zeit/next-less](https://github.com/vercel/next-plugins/tree/master/packages/next-less)
 - [@next/mdx](https://github.com/vercel/next.js/tree/canary/packages/next-mdx)
 - [@next/bundle-analyzer](https://github.com/vercel/next.js/tree/canary/packages/next-bundle-analyzer)
 
@@ -20,12 +26,8 @@ module.exports = {
   webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
     // Note: we provide webpack above so you should not `require` it
     // Perform customizations to webpack config
-    // Important: return the modified config
     config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//))
-    return config
-  },
-  webpackDevMiddleware: (config) => {
-    // Perform customizations to webpack dev middleware config
+
     // Important: return the modified config
     return config
   },

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

@@ -92,3 +92,5 @@ module.exports = {
   },
 }
 ```
+
+In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the `statusCode` property instead of the `permanent` property, but not both. Note: to ensure IE11 compatibility a `Refresh` header is automatically added for the 308 status code.

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

@@ -4,7 +4,7 @@ description: Add rewrites to your Next.js app.
 
 # Rewrites
 
-<details>
+<details open>
   <summary><b>Examples</b></summary>
   <ul>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/rewrites">Rewrites</a></li>

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

@@ -4,6 +4,14 @@ description: Next.js supports including CSS files as Global CSS or CSS Modules,
 
 # Built-In CSS Support
 
+<details open>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/basic-css">Basic CSS Example</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-tailwindcss">With Tailwind CSS</a></li>
+  </ul>
+</details>
+
 Next.js allows you to import CSS files from a JavaScript file.
 This is possible because Next.js extends the concept of [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) beyond JavaScript.
 
@@ -129,8 +137,8 @@ module.exports = {
 
 To support importing `.less` or `.styl` files you can use the following plugins:
 
-- [@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)
+- [@zeit/next-less](https://github.com/vercel/next-plugins/tree/master/packages/next-less)
+- [@zeit/next-stylus](https://github.com/vercel/next-plugins/tree/master/packages/next-stylus)
 
 If using the less plugin, don't forget to add a dependency on less as well, otherwise you'll see an error like:
 
@@ -143,8 +151,10 @@ Error: Cannot find module 'less'
 <details>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/basic-css">Styled JSX</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-styled-jsx">Styled JSX</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-styled-components">Styled Components</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-emotion">Emotion</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-tailwindcss-emotion">Tailwind CSS + Emotion</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-styletron">Styletron</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-glamor">Glamor</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-cxs">Cxs</a></li>
@@ -164,7 +174,7 @@ function HiThere() {
 export default HiThere
 ```
 
-We bundle [styled-jsx](https://github.com/zeit/styled-jsx) to provide support for isolated scoped CSS.
+We bundle [styled-jsx](https://github.com/vercel/styled-jsx) to provide support for isolated scoped CSS.
 The aim is to support "shadow CSS" similar to Web Components, which unfortunately [do not support server-rendering and are JS-only](https://github.com/w3c/webcomponents/issues/71).
 
 See the above examples for other popular CSS-in-JS solutions (like Styled Components).
@@ -202,7 +212,7 @@ function HelloWorld() {
 export default HelloWorld
 ```
 
-Please see the [styled-jsx documentation](https://github.com/zeit/styled-jsx) for more examples.
+Please see the [styled-jsx documentation](https://github.com/vercel/styled-jsx) for more examples.
 
 ## FAQ
 

docs/basic-features/data-fetching.md

@@ -54,6 +54,11 @@ The `context` parameter is an object containing the following keys:
 - `preview` is `true` if the page is in the preview mode and `false` otherwise. See the [Preview Mode documentation](/docs/advanced-features/preview-mode.md).
 - `previewData` contains the preview data set by `setPreviewData`. See the [Preview Mode documentation](/docs/advanced-features/preview-mode.md).
 
+`getStaticProps` should return an object with:
+
+- `props` - A **required** object with the props that will be received by the page component. It should be a [serializable object](https://en.wikipedia.org/wiki/Serialization)
+- `revalidate` - An **optional** amount in seconds after which a page re-generation can occur. More on [Incremental Static Regeneration](#incremental-static-regeneration)
+
 > **Note**: You can import modules in top-level scope for use in `getStaticProps`.
 > Imports used in `getStaticProps` will not be bundled for the client-side, as [explained below](#write-server-side-code-directly).
 
@@ -143,6 +148,67 @@ function Blog({ posts }: InferGetStaticPropsType<typeof getStaticProps>) {
 export default Blog
 ```
 
+### Incremental Static Regeneration
+
+> This feature was introduced in [Next.js 9.5](https://nextjs.org/blog/next-9-5#stable-incremental-static-regeneration) and up. If you’re using older versions of Next.js, please upgrade before trying Incremental Static Regeneration.
+
+<details open>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://reactions-demo.now.sh/">Static Reactions Demo</a></li>
+  </ul>
+</details>
+
+With [`getStaticProps`](#getstaticprops-static-generation) you don't have to stop relying in dynamic content, as **static content can also be dynamic**. Incremental Static Regeneration allows you to update _existing_ pages by re-rendering them in the background as traffic comes in.
+
+Inspired by [stale-while-revalidate](https://tools.ietf.org/html/rfc5861), background regeneration ensures traffic is served uninterruptedly, always from static storage, and the newly built page is pushed only after it's done generating.
+
+Consider our previous [`getStaticProps` example](#simple-example), but now with regeneration enabled:
+
+```jsx
+function Blog({ posts }) {
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li>{post.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+// This function gets called at build time on server-side.
+// It may be called again, on a serverless function, if
+// revalidation is enabled and a new request comes in
+export async function getStaticProps() {
+  const res = await fetch('https://.../posts')
+  const posts = await res.json()
+
+  return {
+    props: {
+      posts,
+    },
+    // Next.js will attempt to re-generate the page:
+    // - When a request comes in
+    // - At most once every second
+    revalidate: 1, // In seconds
+  }
+}
+
+export default Blog
+```
+
+Now the list of blog posts will be revalidated once per second; if you add a new blog post it will be available almost immediately, without having to re-build your app or make a new deployment.
+
+This works perfectly with [`fallback: true`](#fallback-true). Because now you can have a list of posts that's always up to date with the latest posts, and have a [blog post page](#fallback-pages) that generates blog posts on-demand, no matter how many posts you add or update.
+
+#### Static content at scale
+
+Unlike traditional SSR, [Incremental Static Regeneration](#incremental-static-regeneration) ensures you retain the benefits of static:
+
+- No spikes in latency. Pages are served consistently fast
+- Pages never go offline. If the background page re-generation fails, the old page remains unaltered
+- Low database and backend load. Pages are re-computed at most once concurrently
+
 ### Reading files: Use `process.cwd()`
 
 Files can be read directly from the filesystem in `getStaticProps`.
@@ -326,6 +392,13 @@ export default Post
 
 #### `fallback: true`
 
+<details>
+  <summary><b>Examples</b></summary>
+  <ul>
+    <li><a href="https://static-tweet.now.sh">Static generation of a large number of pages</a></li>
+  </ul>
+</details>
+
 If `fallback` is `true`, then the behavior of `getStaticProps` changes:
 
 - The paths returned from `getStaticPaths` will be rendered to HTML at build time.
@@ -380,7 +453,12 @@ export async function getStaticProps({ params }) {
   const post = await res.json()
 
   // Pass post data to the page via props
-  return { props: { post } }
+  return {
+    props: { post },
+    // Re-generate the post at most once per second
+    // if a request comes in
+    revalidate: 1,
+  }
 }
 
 export default Post
@@ -394,6 +472,8 @@ Instead, you may statically generate a small subset of pages and use `fallback:
 
 This ensures that users always have a fast experience while preserving fast builds and the benefits of Static Generation.
 
+`fallback: true` will not _update_ generated pages, for that take a look at [Incremental Static Regeneration](#incremental-static-regeneration).
+
 ### When should I use `getStaticPaths`?
 
 You should use `getStaticPaths` if you’re statically pre-rendering pages that use dynamic routes.

docs/routing/dynamic-routes.md

@@ -99,7 +99,7 @@ The `query` objects are as follows:
 { "slug": ["a", "b"] } // `GET /post/a/b` (multi-element array)
 ```
 
-> A good example of optional catch all routes is the Next.js docs, a single page called [pages/docs/[[...slug]].js](https://github.com/zeit/next-site/blob/master/pages/docs/%5B%5B...slug%5D%5D.js) takes care of all the docs you're currently looking at.
+> A good example of optional catch all routes is the Next.js docs, a single page called [pages/docs/[[...slug]].js](https://github.com/vercel/next-site/blob/master/pages/docs/%5B%5B...slug%5D%5D.js) takes care of all the docs you're currently looking at.
 
 ## Caveats
 

docs/upgrading.md

@@ -104,7 +104,7 @@ Next.js now has the concept of page-level configuration, so the `withAmp` higher
 This change can be **automatically migrated by running the following commands in the root of your Next.js project:**
 
 ```bash
-curl -L https://github.com/zeit/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/withamp-to-config.js npx jscodeshift -t ./withamp-to-config.js pages/**/*.js
+curl -L https://github.com/vercel/next-codemod/archive/master.tar.gz | tar -xz --strip=2 next-codemod-master/transforms/withamp-to-config.js npx jscodeshift -t ./withamp-to-config.js pages/**/*.js
 ```
 
 To perform this migration by hand, or view what the codemod will produce, see below: