next lint + ESLint in Create Next App

docs/api-reference/cli.md

@@ -21,7 +21,7 @@ Usage
   $ next <command>
 
 Available commands
-  build, start, export, dev, telemetry
+  build, start, export, dev, lint, telemetry
 
 Options
   --version, -v   Version number
@@ -84,6 +84,16 @@ The application will start at `http://localhost:3000` by default. The default po
 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.
+
+You can also run ESLint on other directories with the `--dir` flag:
+
+```bash
+next lint --dir components
+```
+
 ## Telemetry
 
 Next.js collects **completely anonymous** telemetry data about general usage.

docs/basic-features/eslint.md

@@ -0,0 +1,119 @@
+---
+description: Next.js supports ESLint by default. You can get started with ESLint in Next.js here.
+---
+
+# 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`:
+
+```bash
+next lint
+```
+
+If you don't already have ESLint configured in your application, you will be guided through the installation of any required packages.
+
+```bash
+next lint
+
+# You'll see instructions like these:
+#
+# Please install eslint and eslint-config-next by running:
+#
+#         yarn add --dev eslint eslint-config-next
+#
+# ...
+```
+
+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:
+
+```
+{
+  "extends": "next"
+}
+```
+
+Now you can 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.
+
+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).
+
+## 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`:
+
+```bash
+next lint --dir components --dir lib
+```
+
+## 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).
+
+## Base Configuration
+
+The Next.js base ESLint configuration is automatically generated when `next lint` is run for the first time:
+
+```
+{
+  "extends": "next"
+}
+```
+
+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:
+
+```
+{
+  "extends": "next",
+  "rules": {
+    "react/no-unescaped-entities": "off",
+    "@next/next/no-page-custom-font": "error",
+  }
+}
+```
+
+> **Note**: If you need to also include a separate, custom ESLint configuration, it is highly recommended that `eslint-config-next` is extended last after other configurations. For example:
+>
+> ```
+> {
+>   "extends": ["eslint:recommended", "next"]
+> }
+> ```
+>
+> The `next` configuration already handles setting default values for the `parser`, `plugins` and `settings` properties.
+> There is no need to manually re-declare any of these properties unless you need a different configuration for your use case.
+> If you include any other shareable configurations, you will need to make sure that these properties are not overwritten or modified.
+
+### Core Web Vitals
+
+A stricter `next/core-web-vitals` entrypoint can also be specified in `.eslintrc`:
+
+```
+{
+  "extends": ["next", "next/core-web-vitals"]
+}
+```
+
+`next/core-web-vitals` updates `eslint-plugin-next` to error on a number of rules that are warnings by default if they affect [Core Web Vitals](https://web.dev/vitals/).
+
+> Both `next` and `next/core-web-vitals` entry points are automatically included for new applications built with [Create Next App](/docs/api-reference/create-next-app.md).

docs/getting-started.md

@@ -55,7 +55,8 @@ Open `package.json` and add the following `scripts`:
 "scripts": {
   "dev": "next dev",
   "build": "next build",
-  "start": "next start"
+  "start": "next start",
+  "lint": "next lint"
 }
 ```
 
@@ -64,6 +65,7 @@ These scripts refer to the different stages of developing an application:
 - `dev` - Runs [`next dev`](/docs/api-reference/cli.md#development) which starts Next.js in development mode
 - `build` - Runs [`next build`](/docs/api-reference/cli.md#build) which builds the application for production usage
 - `start` - Runs [`next start`](/docs/api-reference/cli.md#production) which starts a Next.js production server
+- `lint` - Runs [`next lint`](/docs/api-reference/cli.md#lint) which sets up Next.js' built-in ESLint configuration
 
 Next.js is built around the concept of [pages](/docs/basic-features/pages.md). 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.
 

docs/manifest.json

@@ -37,6 +37,10 @@
               "title": "Fast Refresh",
               "path": "/docs/basic-features/fast-refresh.md"
             },
+            {
+              "title": "ESLint",
+              "path": "/docs/basic-features/eslint.md"
+            },
             {
               "title": "TypeScript",
               "path": "/docs/basic-features/typescript.md"

packages/create-next-app/create-app.ts

@@ -187,6 +187,7 @@ export async function createApp({
         dev: 'next dev',
         build: 'next build',
         start: 'next start',
+        lint: 'next lint',
       },
     }
     /**
@@ -207,7 +208,7 @@ export async function createApp({
     /**
      * Default devDependencies.
      */
-    const devDependencies = []
+    const devDependencies = ['eslint', 'eslint-config-next']
     /**
      * TypeScript projects will have type definitions and other devDependencies.
      */
@@ -250,7 +251,8 @@ export async function createApp({
       cwd: path.join(__dirname, 'templates', template),
       rename: (name) => {
         switch (name) {
-          case 'gitignore': {
+          case 'gitignore':
+          case 'eslintrc': {
             return '.'.concat(name)
           }
           // README.md is ignored by webpack-asset-relocator-loader used by ncc:

packages/create-next-app/templates/default/eslintrc

@@ -0,0 +1,3 @@
+{
+  "extends": ["next", "next/core-web-vitals"]
+}

packages/create-next-app/templates/default/pages/api/hello.js

@@ -1,5 +1,5 @@
 // Next.js API route support: https://nextjs.org/docs/api-routes/introduction
 
-export default (req, res) => {
+export default function handler(req, res) {
   res.status(200).json({ name: 'John Doe' })
 }

packages/create-next-app/templates/typescript/eslintrc

@@ -0,0 +1,3 @@
+{
+  "extends": ["next", "next/core-web-vitals"]
+}

packages/create-next-app/templates/typescript/pages/api/hello.ts

@@ -5,6 +5,9 @@ type Data = {
   name: string
 }
 
-export default (req: NextApiRequest, res: NextApiResponse<Data>) => {
+export default function handler(
+  req: NextApiRequest,
+  res: NextApiResponse<Data>
+) {
   res.status(200).json({ name: 'John Doe' })
 }

packages/eslint-config-next/core-web-vitals.js

@@ -0,0 +1,8 @@
+module.exports = {
+  extends: ['.'].map(require.resolve),
+  rules: {
+    '@next/next/no-sync-scripts': 2,
+    '@next/next/no-html-link-for-pages': 2,
+    '@next/next/no-img-element': 2,
+  },
+}

packages/eslint-config-next/index.js

@@ -16,6 +16,7 @@ module.exports = {
   rules: {
     'import/no-anonymous-default-export': 'warn',
     'react/react-in-jsx-scope': 'off',
+    'react/prop-types': 'off',
     'jsx-a11y/alt-text': [
       'warn',
       {

packages/eslint-plugin-next/lib/rules/no-sync-scripts.js

@@ -18,7 +18,7 @@ module.exports = function (context) {
         context.report({
           node,
           message:
-            'Synchronous scripts are forbidden. See: https://nextjs.org/docs/messages/no-sync-scripts.',
+            'External synchronous scripts are forbidden. See: https://nextjs.org/docs/messages/no-sync-scripts.',
         })
       }
     },

packages/next/bin/next.ts

@@ -20,6 +20,7 @@ const commands: { [command: string]: () => Promise<cliCommand> } = {
   start: () => import('../cli/next-start').then((i) => i.nextStart),
   export: () => import('../cli/next-export').then((i) => i.nextExport),
   dev: () => import('../cli/next-dev').then((i) => i.nextDev),
+  lint: () => import('../cli/next-lint').then((i) => i.nextLint),
   telemetry: () => import('../cli/next-telemetry').then((i) => i.nextTelemetry),
 }
 

packages/next/build/index.ts

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

packages/next/cli/next-build.ts

@@ -13,6 +13,7 @@ const nextBuild: cliCommand = (argv) => {
     '--help': Boolean,
     '--profile': Boolean,
     '--debug': Boolean,
+    '--no-lint': Boolean,
     // Aliases
     '-h': '--help',
     '-d': '--debug',
@@ -41,13 +42,17 @@ const nextBuild: cliCommand = (argv) => {
 
       Options
       --profile     Can be used to enable React Production Profiling
+      --no-lint     Disable linting
     `,
       0
     )
   }
   if (args['--profile']) {
     Log.warn('Profiling is enabled. Note: This may affect performance')
   }
+  if (args['--no-lint']) {
+    Log.warn('Linting is disabled')
+  }
   const dir = resolve(args._[0] || '.')
 
   // Check if the provided directory exists
@@ -93,7 +98,9 @@ const nextBuild: cliCommand = (argv) => {
   }
 
   return preflight()
-    .then(() => build(dir, null, args['--profile'], args['--debug']))
+    .then(() =>
+      build(dir, null, args['--profile'], args['--debug'], !args['--no-lint'])
+    )
     .catch((err) => {
       console.error('')
       console.error('> Build error occurred')