ESLint Updates

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

docs/api-reference/next.config.js/ignoring-eslint.md

@@ -0,0 +1,41 @@
+---
+description: Next.js reports ESLint errors and warnings during builds by default. Learn 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: {
+    // !! WARN !!
+    // Dangerously allow production builds to successfully complete even if
+    // your project has ESLint errors.
+    // !! WARN !!
+    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>

docs/basic-features/eslint.md

@@ -7,13 +7,13 @@ description: Next.js provides an integrated ESLint experience by default. These
 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`:
 
 ```bash
-next lint
+npx next lint
 ```
 
 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
+npx next lint
 
 # You'll see instructions like these:
 #
@@ -42,25 +42,36 @@ We recommend using an appropriate [integration](https://eslint.org/docs/user-gui
 
 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:
-
-```bash
-next build --no-lint
-```
-
-**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).
+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):
 
 ## Linting Custom Directories
 
-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`:
+By default, Next.js will run ESLint for all files in the `pages/`, `components/`, and `lib/` directories. However, you can specify other custom directories to run by using the `--dir` flag in `next lint`:
 
 ```bash
-next lint --dir components --dir lib
+npx next lint --dir utils --dir custom
 ```
 
 ## ESLint Plugin
 
-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 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 <img> 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 <title> 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
 
@@ -82,14 +93,14 @@ You can see the full details of the shareable configuration in the [`eslint-conf
 
 ## Disabling Rules
 
-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 in your `.eslintrc`:
+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",
   }
 }
 ```

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"

packages/next/build/index.ts

@@ -119,8 +119,7 @@ export default async function build(
   dir: string,
   conf = null,
   reactProductionProfiling = false,
-  debugOutput = false,
-  runLint = true
+  debugOutput = false
 ): Promise<void> {
   const nextBuildSpan = trace('next-build')
 
@@ -213,7 +212,7 @@ export default async function build(
       typeCheckingSpinner.stopAndPersist()
     }
 
-    if (runLint) {
+    if (!Boolean(config.eslint?.ignoreDuringBuilds)) {
       await nextBuildSpan
         .traceChild('verify-and-lint')
         .traceAsyncFn(async () => {

packages/next/cli/next-build.ts

@@ -98,9 +98,7 @@ const nextBuild: cliCommand = (argv) => {
   }
 
   return preflight()
-    .then(() =>
-      build(dir, null, args['--profile'], args['--debug'], !args['--no-lint'])
-    )
+    .then(() => build(dir, null, args['--profile'], args['--debug']))
     .catch((err) => {
       console.error('')
       console.error('> Build error occurred')

packages/next/cli/next-lint.ts

@@ -2,6 +2,8 @@
 import { existsSync } from 'fs'
 import arg from 'next/dist/compiled/arg/index.js'
 import { resolve, join } from 'path'
+import chalk from 'chalk'
+
 import { cliCommand } from '../bin/next'
 import { runLintCheck } from '../lib/eslint/runLintCheck'
 import { printAndExit } from '../server/lib/utils'
@@ -66,7 +68,11 @@ const nextLint: cliCommand = (argv) => {
 
   runLintCheck(baseDir, lintDirs)
     .then((results) => {
-      if (results) console.log(results)
+      if (results) {
+        console.log(results)
+      } else {
+        console.log(chalk.green('✔ No ESLint warnings or errors'))
+      }
     })
     .catch((err) => {
       printAndExit(err.message)

packages/next/lib/eslint/customFormatter.ts

@@ -70,12 +70,15 @@ function formatMessage(
 }
 
 export function formatResults(baseDir: string, results: LintResult[]): string {
-  return (
-    results
-      .filter(({ messages }) => messages?.length)
-      .map(({ messages, filePath }) =>
-        formatMessage(baseDir, messages, filePath)
-      )
-      .join('\n') + '\n'
-  )
+  const formattedResults = results
+    .filter(({ messages }) => messages?.length)
+    .map(({ messages, filePath }) => formatMessage(baseDir, messages, filePath))
+    .join('\n')
+
+  return formattedResults.length > 0
+    ? formattedResults +
+        `\n\n${chalk.bold(
+          'Need to disable some ESLint rules? Learn more here:'
+        )} https://nextjs.org/docs/basic-features/eslint#disabling-rules\n`
+    : ''
 }

packages/next/lib/eslint/runLintCheck.ts

@@ -7,9 +7,10 @@ import * as CommentJson from 'next/dist/compiled/comment-json'
 
 import { formatResults } from './customFormatter'
 import { writeDefaultConfig } from './writeDefaultConfig'
+
 import { getPackageVersion } from '../get-package-version'
+import { findDir } from '../find-dir'
 import { findPagesDir } from '../find-pages-dir'
-
 import { CompileError } from '../compile-error'
 import {
   hasNecessaryDependencies,
@@ -74,6 +75,8 @@ async function lint(
   }
 
   const pagesDir = findPagesDir(baseDir)
+  const componentsDir = findDir(baseDir, 'components')
+  const libDir = findDir(baseDir, 'lib')
 
   if (nextEslintPluginIsEnabled) {
     let updatedPagesDir = false
@@ -98,10 +101,12 @@ async function lint(
     }
   }
 
-  // If no directories to lint are provided, only the pages directory will be linted
+  // If no directories to lint are provided, the pages, components, and lib directories will be linted
   const filesToLint = lintDirs
     ? lintDirs.map(linteableFiles)
-    : linteableFiles(pagesDir)
+    : [pagesDir, componentsDir, libDir]
+        .filter((dir) => dir && dir.length > 0)
+        .map(linteableFiles)
 
   const results = await eslint.lintFiles(filesToLint)
 

packages/next/lib/find-dir.ts

@@ -0,0 +1,13 @@
+import path from 'path'
+import { existsSync } from './find-pages-dir'
+
+export function findDir(dir: string, dirName: string): string {
+  // prioritize ./pages over ./src/pages
+  let curDir = path.join(dir, dirName)
+  if (existsSync(curDir)) return curDir
+
+  curDir = path.join(dir, dirName)
+  if (existsSync(curDir)) return curDir
+
+  return ''
+}

packages/next/lib/has-necessary-dependencies.ts

@@ -70,18 +70,15 @@ export async function hasNecessaryDependencies(
   const removalLintMsg =
     `\n\n` +
     (lintDuringBuild
-      ? `If you do not want to run ESLint during builds, run ${chalk.bold.cyan(
-          'next build --no-lint'
-        )}` +
+      ? `If you do not want to run ESLint during builds, ` +
         (!!eslintrcFile
-          ? ` or remove the ${chalk.bold(
+          ? `remove the ${chalk.bold(
               basename(eslintrcFile)
-            )} file from your package root.`
+            )} file from your package root`
           : pkgJsonEslintConfig
-          ? ` or remove the ${chalk.bold(
-              'eslintConfig'
-            )} field from package.json.`
-          : '')
+          ? `remove the ${chalk.bold('eslintConfig')} field from package.json`
+          : '') +
+        ' or disable it in next.config.js.\n\nSee https://nextjs.org/docs/api-reference/next.config.js/ignoring-eslint.'
       : `Once installed, run ${chalk.bold.cyan('next lint')} again.`)
   const removalMsg = checkTSDeps ? removalTSMsg : removalLintMsg
 

test/integration/eslint/ignore-during-builds/.eslintrc

@@ -0,0 +1,7 @@
+{
+  "extends": "next",
+  "root": true,
+  "rules": {
+    "@next/next/no-html-link-for-pages": 0
+  }
+}

test/integration/eslint/ignore-during-builds/next.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  eslint: {
+    // !! WARN !!
+    // Dangerously allow production builds to successfully complete even if
+    // your project has ESLint errors.
+    // !! WARN !!
+    ignoreDuringBuilds: true,
+  },
+}

test/integration/eslint/ignore-during-builds/pages/index.js

@@ -0,0 +1,8 @@
+const Home = () => (
+  <div>
+    <p>Home</p>
+    /* Badly formatted comment */
+  </div>
+)
+
+export default Home