Merge branch 'canary' into remove-types-comment-json

vercel · Jun 9, 2021 · f3723da · f3723da
2 parents da657fa + ce4e1af
commit f3723da
Show file tree

Hide file tree

Showing 274 changed files with 2,005 additions and 792 deletions.
diff --git a/.github/workflows/build_test_deploy.yml b/.github/workflows/build_test_deploy.yml
@@ -156,15 +156,15 @@ jobs:
     steps:
       - run: exit 0
 
-  testFutureDependencies:
-    name: Webpack 5 (Basic, Production, Acceptance)
+  testLegacyWebpack:
+    name: Webpack 4 (Basic, Production, Acceptance)
     runs-on: ubuntu-latest
     needs: build
     env:
       NEXT_TELEMETRY_DISABLED: 1
       NEXT_TEST_JOB: 1
       HEADLESS: true
-      NEXT_PRIVATE_TEST_WEBPACK5_MODE: 1
+      NEXT_PRIVATE_TEST_WEBPACK4_MODE: 1
 
     steps:
       - uses: actions/cache@v2
@@ -174,43 +174,9 @@ jobs:
           path: ./*
           key: ${{ github.sha }}
 
-      - run: xvfb-run node run-tests.js test/integration/{fallback-modules,link-ref,production,basic,async-modules,font-optimization,ssr-ctx}/test/index.test.js test/acceptance/*.test.js
+      - run: xvfb-run node run-tests.js test/integration/{basic,fallback-modules,link-ref,production,async-modules,font-optimization,ssr-ctx}/test/index.test.js test/acceptance/*.test.js
         if: ${{needs.build.outputs.docsChange != 'docs only change'}}
 
-  testLegacyReact:
-    name: React 16 + Webpack 4 (Basic, Production, Acceptance)
-    runs-on: ubuntu-latest
-    env:
-      NEXT_TELEMETRY_DISABLED: 1
-      NEXT_TEST_JOB: 1
-      HEADLESS: true
-
-    steps:
-      - uses: actions/checkout@v2
-        with:
-          fetch-depth: 25
-
-      - run: echo ::set-output name=DOCS_CHANGE::$(node skip-docs-change.js echo 'not-docs-only-change')
-        id: docs-change
-
-      - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
-        if: ${{ steps.docs-change.outputs.DOCS_CHANGE != 'docs only change' }}
-
-      - run: cat package.json | jq '.resolutions.react = "^16.14.0"' > package.json.tmp && mv package.json.tmp package.json
-        if: ${{ steps.docs-change.outputs.DOCS_CHANGE != 'docs only change' }}
-
-      - run: cat package.json | jq '.resolutions."react-dom" = "^16.14.0"' > package.json.tmp && mv package.json.tmp package.json
-        if: ${{ steps.docs-change.outputs.DOCS_CHANGE != 'docs only change' }}
-
-      - run: yarn install --check-files
-        if: ${{ steps.docs-change.outputs.DOCS_CHANGE != 'docs only change' }}
-
-      - run: yarn list react react-dom
-        if: ${{ steps.docs-change.outputs.DOCS_CHANGE != 'docs only change' }}
-
-      - run: xvfb-run node run-tests.js test/integration/{link-ref,production,basic,async-modules,font-optimization,ssr-ctx,worker-loader}/test/index.test.js test/acceptance/*.test.js
-        if: ${{ steps.docs-change.outputs.DOCS_CHANGE != 'docs only change' }}
-
   testFirefox:
     name: Test Firefox (production)
     runs-on: ubuntu-latest

diff --git a/contributing.md b/contributing.md
@@ -124,12 +124,19 @@ When you add an example to the [examples](examples) directory, don’t forget to
 - To add additional installation instructions, please add it where appropriate.
 - To add additional notes, add `## Notes` section at the end.
 - Remove the `Deploy your own` section if your example can’t be immediately deployed to Vercel.
+- Remove the `Preview` section if the example doesn't work on [StackBlitz](http://stackblitz.com/) and file an issue [here](https://github.com/stackblitz/webcontainer-core).
 
 ````markdown
 # Example Name
 
 Description
 
+## Preview
+
+Preview the example live on [StackBlitz](http://stackblitz.com/):
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/vercel/next.js/tree/canary/examples/DIRECTORY_NAME)
+
 ## Deploy your own
 
 Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example):

diff --git a/docs/api-reference/cli.md b/docs/api-reference/cli.md
@@ -86,12 +86,15 @@ npx next start -p 4000
 
 ## Lint
 
-`next lint` runs ESLint for all files in the `pages` directory and provides a guided setup to install any required dependencies if ESLint is not already configured in your application.
+`next lint` runs ESLint for all files in the `pages`, `components`, and `lib` directories. It also
+provides a guided setup to install any required dependencies if ESLint is not already configured in
+your application.
 
-You can also run ESLint on other directories with the `--dir` flag:
+If you have other directories that you would like to lint, you can specify them using the `--dir`
+flag:
 
 ```bash
-next lint --dir components
+next lint --dir utils
 ```
 
 ## Telemetry

diff --git a/docs/api-reference/create-next-app.md b/docs/api-reference/create-next-app.md
@@ -19,6 +19,7 @@ yarn create next-app
 - **-e, --example [name]|[github-url]** - An example to bootstrap the app with. You can use an example name from the [Next.js repo](https://github.com/vercel/next.js/tree/master/examples) or a GitHub URL. The URL can use any branch and/or subdirectory.
 - **--example-path [path-to-example]** - In a rare case, your GitHub URL might contain a branch name with a slash (e.g. bug/fix-1) and the path to the example (e.g. foo/bar). In this case, you must specify the path to the example separately: `--example-path foo/bar`
 - **--use-npm** - Explicitly tell the CLI to bootstrap the app using npm. To bootstrap using yarn we recommend to run `yarn create next-app`
+- **--typescript or --ts** - Creates the default template with TypeScript instead of JavaScript.
 
 ### Why use Create Next App?
 

diff --git a/docs/api-reference/next.config.js/ignoring-eslint.md b/docs/api-reference/next.config.js/ignoring-eslint.md
@@ -0,0 +1,39 @@
+---
+description: Next.js reports ESLint errors and warnings during builds by default. Learn how to opt-out of this behavior here.
+---
+
+# Ignoring ESLint
+
+When ESLint is detected in your project, Next.js fails your **production build** (`next build`) when errors are present.
+
+If you'd like Next.js to dangerously produce production code even when your application has ESLint errors, you can disable the built-in linting step completely.
+
+> Be sure you have configured ESLint to run in a separate part of your workflow (for example, in CI or a pre-commit hook).
+
+Open `next.config.js` and enable the `ignoreDuringBuilds` option in the `eslint` config:
+
+```js
+module.exports = {
+  eslint: {
+    // Warning: Dangerously allow production builds to successfully complete even if
+    // your project has ESLint errors.
+    ignoreDuringBuilds: true,
+  },
+}
+```
+
+## Related
+
+<div class="card">
+  <a href="/docs/api-reference/next.config.js/introduction.md">
+    <b>Introduction to next.config.js:</b>
+    <small>Learn more about the configuration file used by Next.js.</small>
+  </a>
+</div>
+
+<div class="card">
+  <a href="/docs/basic-features/eslint.md">
+    <b>ESLint:</b>
+    <small>Get started with ESLint in Next.js.</small>
+  </a>
+</div>
diff --git a/docs/basic-features/eslint.md b/docs/basic-features/eslint.md
@@ -1,19 +1,27 @@
 ---
-description: Next.js supports ESLint by default. You can get started with ESLint in Next.js here.
+description: Next.js provides an integrated ESLint experience by default. These conformance rules help you use Next.js in the optimal way.
 ---
 
 # ESLint
 
-Since version **11.0.0**, Next.js provides an integrated [ESLint](https://eslint.org/) experience out of the box. To get started, run `next lint`:
+Since version **11.0.0**, Next.js provides an integrated [ESLint](https://eslint.org/) experience out of the box. Add `next lint` as a script to `package.json`:
+
+```json
+"scripts": {
+  "lint": "next lint"
+}
+```
+
+Then run `npm run lint` or `yarn lint`:
 
 ```bash
-next lint
+yarn lint
 ```
 
-If you don't already have ESLint configured in your application, you will be guided through the installation of any required packages.
+If you don't already have ESLint configured in your application, you will be guided through the installation of the required packages.
 
 ```bash
-next lint
+yarn lint
 
 # You'll see instructions like these:
 #
@@ -26,68 +34,91 @@ next lint
 
 If no ESLint configuration is present, Next.js will create an `.eslintrc` file in the root of your project and automatically configure it with the base configuration:
 
-```
+```js
 {
   "extends": "next"
 }
 ```
 
-Now you can run `next lint` every time you want to run ESLint to catch errors
+You can now run `next lint` every time you want to run ESLint to catch errors.
 
 > The default base configuration (`"extends": "next"`) can be updated at any time and will only be included if no ESLint configuration is present.
 
 We recommend using an appropriate [integration](https://eslint.org/docs/user-guide/integrations#editors) to view warnings and errors directly in your code editor during development.
 
 ## Linting During Builds
 
-Once ESLint has been set up, it will automatically run during every build (`next build`). Errors will fail the build while warnings will not.
+Once ESLint has been set up, it will automatically run during every build (`next build`). Errors will fail the build, while warnings will not.
 
-If you do not want ESLint to run as a build step, it can be disabled using the `--no-lint` flag:
+If you do not want ESLint to run as a build step, refer to the documentation for [Ignoring ESLint](/docs/api-reference/next.config.js/ignoring-eslint.md):
 
-```bash
-next build --no-lint
-```
+## Linting Custom Directories
 
-This is not recommended unless you have configured ESLint to run in a separate part of your workflow (for example, in CI or a pre-commit hook).
+By default, Next.js will run ESLint for all files in the `pages/`, `components/`, and `lib/` directories. However, you can specify which directories using the `dirs` option in the `eslint` config in `next.config.js` for production builds:
 
-## Linting Custom Directories
+```js
+module.exports = {
+  eslint: {
+    dirs: ['pages', 'utils'], // Only run ESLint on the 'pages' and 'utils' directories during production builds (next build)
+  },
+}
+```
 
-By default, Next.js will only run ESLint for all files in the `pages/` directory. However, you can specify other custom directories to run by using the `--dir` flag in `next lint`:
+Similarly, the `--dir` flag can be used for `next lint`:
 
 ```bash
-next lint --dir components --dir lib
+yarn lint --dir pages --dir utils
 ```
 
 ## ESLint Plugin
 
-Next.js provides an ESLint plugin, [`eslint-plugin-next`](https://www.npmjs.com/package/@next/eslint-plugin-next), that makes it easier to catch common issues and problems in a Next.js application. The full set of rules can be found in the [package repository](https://github.com/vercel/next.js/tree/master/packages/eslint-plugin-next/lib/rules).
+Next.js provides an ESLint plugin, [`eslint-plugin-next`](https://www.npmjs.com/package/@next/eslint-plugin-next), making it easier to catch common issues and problems in a Next.js application. The full set of rules is as follows:
+
+|     | Rule                                                                                           | Description                                                      |
+| :-: | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| ✔️  | [next/google-font-display](https://nextjs.org/docs/messages/google-font-display)               | Enforce optional or swap font-display behavior with Google Fonts |
+| ✔️  | [next/google-font-preconnect](https://nextjs.org/docs/messages/google-font-preconnect)         | Enforce preconnect usage with Google Fonts                       |
+| ✔️  | [next/link-passhref](https://nextjs.org/docs/messages/link-passhref)                           | Enforce passHref prop usage with custom Link components          |
+| ✔️  | [next/no-css-tags](https://nextjs.org/docs/messages/no-css-tags)                               | Prevent manual stylesheet tags                                   |
+| ✔️  | [next/no-document-import-in-page](https://nextjs.org/docs/messages/no-document-import-in-page) | Disallow importing next/document outside of pages/document.js    |
+| ✔️  | [next/no-head-import-in-document](https://nextjs.org/docs/messages/no-head-import-in-document) | Disallow importing next/head in pages/document.js                |
+| ✔️  | [next/no-html-link-for-pages](https://nextjs.org/docs/messages/no-html-link-for-pages)         | Prohibit HTML anchor links to pages without a Link component     |
+| ✔️  | [next/no-img-element](https://nextjs.org/docs/messages/no-img-element)                         | Prohibit usage of HTML &lt;img&gt; element                       |
+| ✔️  | [next/no-page-custom-font](https://nextjs.org/docs/messages/no-page-custom-font)               | Prevent page-only custom fonts                                   |
+| ✔️  | [next/no-sync-scripts](https://nextjs.org/docs/messages/no-sync-scripts)                       | Forbid synchronous scripts                                       |
+| ✔️  | [next/no-title-in-document-head](https://nextjs.org/docs/messages/no-title-in-document-head)   | Disallow using &lt;title&gt; with Head from next/document        |
+| ✔️  | [next/no-unwanted-polyfillio](https://nextjs.org/docs/messages/no-unwanted-polyfillio)         | Prevent duplicate polyfills from Polyfill.io                     |
+
+- ✔: Enabled in the recommended configuration
 
 ## Base Configuration
 
 The Next.js base ESLint configuration is automatically generated when `next lint` is run for the first time:
 
-```
+```js
 {
   "extends": "next"
 }
 ```
 
-This configuration extends recommended rule sets from various Eslint plugins:
+This configuration extends recommended rule sets from various ESLint plugins:
 
 - [`eslint-plugin-react`](https://www.npmjs.com/package/eslint-plugin-react)
 - [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks)
 - [`eslint-plugin-next`](https://www.npmjs.com/package/@next/eslint-plugin-next)
 
 You can see the full details of the shareable configuration in the [`eslint-config-next`](https://www.npmjs.com/package/eslint-config-next) package.
 
-If you would like to modify any rules provided by the supported plugins (`react`, `react-hooks`, `next`), you can directly modify them using the `rules` property:
+## Disabling Rules
 
-```
+If you would like to modify or disable any rules provided by the supported plugins (`react`, `react-hooks`, `next`), you can directly change them using the `rules` property in your `.eslintrc`:
+
+```js
 {
   "extends": "next",
   "rules": {
     "react/no-unescaped-entities": "off",
-    "@next/next/no-page-custom-font": "error",
+    "@next/next/no-page-custom-font": "off",
   }
 }
 ```
@@ -106,7 +137,7 @@ If you would like to modify any rules provided by the supported plugins (`react`
 
 ### Core Web Vitals
 
-A stricter `next/core-web-vitals` entrypoint can also be specified in `.eslintrc`:
+A stricter `next/core-web-vitals` rule set can also be added in `.eslintrc`:
 
 ```
 {

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -344,6 +344,10 @@
               "title": "Configuring onDemandEntries",
               "path": "/docs/api-reference/next.config.js/configuring-onDemandEntries.md"
             },
+            {
+              "title": "Ignoring ESLint",
+              "path": "/docs/api-reference/next.config.js/ignoring-eslint.md"
+            },
             {
               "title": "Ignoring TypeScript Errors",
               "path": "/docs/api-reference/next.config.js/ignoring-typescript-errors.md"

diff --git a/docs/upgrading.md b/docs/upgrading.md
@@ -6,6 +6,22 @@ description: Learn how to upgrade Next.js.
 
 ## Upgrading from version 10 to 11
 
+## Upgrade React version to latest
+
+Most applications already use the latest version of React, with Next.js 11 the minimum React version has been updated to 17.0.2.
+
+To upgrade you can run the following command:
+
+```
+npm install react@latest react-dom@latest
+```
+
+Or using `yarn`:
+
+```
+yarn add react@latest react-dom@latest
+```
+
 ### Remove `super.componentDidCatch()` from `pages/_app.js`
 
 The `next/app` component's `componentDidCatch` has been deprecated since Next.js 9 as it's no longer needed and has since been a no-op, in Next.js 11 it has been removed.

diff --git a/errors/future-webpack5-moved-to-webpack5.md b/errors/future-webpack5-moved-to-webpack5.md
@@ -0,0 +1,33 @@
+# `future.webpack5` has been moved to `webpack5`
+
+#### Why This Error Occurred
+
+The `future.webpack5` option has been moved to `webpack5` in `next.config.js`.
+
+#### Possible Ways to Fix It
+
+If you had the value `true` you can removed the option as webpack 5 is now the default for all Next.js apps unless opted out.
+
+If you had he value `false` you can update `next.config.js`:
+
+Change `future.webpack5` to `webpack5`.
+
+Current `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+  future: {
+    webpack5: false,
+  },
+}
+```
+
+Updated `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+  webpack5: false,
+}
+```
diff --git a/errors/no-document-import-in-page.md b/errors/no-document-import-in-page.md
@@ -2,11 +2,11 @@
 
 ### Why This Error Occurred
 
-`next/document` was imported in a page outside of `pages/_document.js`. This can cause unexpected issues in your application.
+`next/document` was imported in a page outside of `pages/_document.js` (or `pages/_document.tsx` if you are using TypeScript). This can cause unexpected issues in your application.
 
 ### Possible Ways to Fix It
 
-Only import and use `next/document` within `pages/_document.js` to override the default `Document` component:
+Only import and use `next/document` within `pages/_document.js` (or `pages/_document.tsx`) to override the default `Document` component:
 
 ```jsx
 // pages/_document.js