Unverified Commit df83ccb7 authored by Houssein Djirdeh's avatar Houssein Djirdeh Committed by GitHub

[ESLint] Documentation updates + bug fixes (#26331)

Documentation:

- Expands the "Migrating Existing Config" section of ESLint doc to explain in more detail
- Minor changes to the "Ignoring ESLint" doc

Bug fixes:

- Adds `browser` and `node` environments to `eslint-config-next`. Closes #26319
- Fixes `no-document-import` rule. Closes #26159
- Fixes `no-page-custom-font` rule. Closes #26160 #26894
parent 0593dbb2
...@@ -6,16 +6,14 @@ description: Next.js reports ESLint errors and warnings during builds by default ...@@ -6,16 +6,14 @@ description: Next.js reports ESLint errors and warnings during builds by default
When ESLint is detected in your project, Next.js fails your **production build** (`next build`) when errors are present. 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. If you'd like Next.js to produce production code even when your application has ESLint errors, you can disable the built-in linting step completely. This is not recommended unless you already have ESLint configured to run in a separate part of your workflow (for example, in CI or a pre-commit hook).
> 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: Open `next.config.js` and enable the `ignoreDuringBuilds` option in the `eslint` config:
```js ```js
module.exports = { module.exports = {
eslint: { eslint: {
// Warning: Dangerously allow production builds to successfully complete even if // Warning: This allows production builds to successfully complete even if
// your project has ESLint errors. // your project has ESLint errors.
ignoreDuringBuilds: true, ignoreDuringBuilds: true,
}, },
......
...@@ -132,18 +132,6 @@ If you would like to modify or disable any rules provided by the supported plugi ...@@ -132,18 +132,6 @@ If you would like to modify or disable any rules provided by the supported plugi
} }
``` ```
> **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 ### Core Web Vitals
The `next/core-web-vitals` rule set is enabled when `next lint` is run for the first time and the **strict** option is selected. The `next/core-web-vitals` rule set is enabled when `next lint` is run for the first time and the **strict** option is selected.
...@@ -170,7 +158,19 @@ ESLint also contains code formatting rules, which can conflict with your existin ...@@ -170,7 +158,19 @@ ESLint also contains code formatting rules, which can conflict with your existin
## Migrating Existing Config ## Migrating Existing Config
If you already have ESLint configured in your application, we recommend extending directly from the Next.js ESLint plugin instead of the shareable configuration. ### Recommended Plugin Ruleset
If you already have ESLint configured in your application and any of the following conditions are true:
- You have one or more of the following plugins already installed (either separately or through a different config such as `airbnb` or `react-app`):
- `react`
- `react-hooks`
- `jsx-a11y`
- `import`
- You've defined specific `parserOptions` that are different from how Babel is configured within Next.js (this is not recommended unless you have [customized your Babel configuration](/docs/advanced-features/customizing-babel-config.md))
- You have `eslint-plugin-import` installed with Node.js and/or TypeScript [resolvers](https://github.com/benmosher/eslint-plugin-import#resolvers) defined to handle imports
Then we recommend either removing these settings if you prefer how these properties have been configured within [`eslint-config-next`](https://github.com/vercel/next.js/blob/canary/packages/eslint-config-next/index.js) or extending directly from the Next.js ESLint plugin instead:
```js ```js
module.exports = { module.exports = {
...@@ -181,4 +181,24 @@ module.exports = { ...@@ -181,4 +181,24 @@ module.exports = {
} }
``` ```
This eliminates any risk of collisions that can occur due to importing the same plugin or parser across multiple configurations. The plugin can be installed normally in your project without needing to run `next lint`:
```bash
npm install --save-dev eslint-plugin-next
# or
yarn add --dev eslint-plugin-next
```
This eliminates the risk of collisions or errors that can occur due to importing the same plugin or parser across multiple configurations.
### Additional Configurations
If you already use a separate ESLint configuration and want to include `eslint-config-next`, ensure that it 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**. Otherwise, we recommend removing any configurations that share behavior with the `next` configuration or extending directly from the Next.js ESLint plugin as mentioned above.
...@@ -72,4 +72,8 @@ module.exports = { ...@@ -72,4 +72,8 @@ module.exports = {
}, },
}, },
}, },
env: {
browser: true,
node: true,
},
} }
...@@ -16,7 +16,12 @@ module.exports = { ...@@ -16,7 +16,12 @@ module.exports = {
} }
const page = context.getFilename().split('pages')[1] const page = context.getFilename().split('pages')[1]
if (!page || path.parse(page).name.startsWith('_document')) { const { name, dir } = path.parse(page)
if (
!page ||
name.startsWith('_document') ||
(dir === '/_document' && name === 'index')
) {
return return
} }
......
...@@ -15,14 +15,21 @@ module.exports = { ...@@ -15,14 +15,21 @@ module.exports = {
} }
const document = context.getFilename().split('pages')[1] const document = context.getFilename().split('pages')[1]
if (!document || !path.parse(document).name.startsWith('_document')) { if (!document) {
return return
} }
const { name, dir } = path.parse(document)
if (
name.startsWith('_document') ||
(dir === '/_document' && name === 'index')
) {
context.report({ context.report({
node, node,
message: `next/head should not be imported in pages${document}. Import Head from next/document instead. See https://nextjs.org/docs/messages/no-head-import-in-document.`, message: `next/head should not be imported in pages${document}. Import Head from next/document instead. See https://nextjs.org/docs/messages/no-head-import-in-document.`,
}) })
}
}, },
} }
}, },
......
...@@ -9,12 +9,15 @@ module.exports = { ...@@ -9,12 +9,15 @@ module.exports = {
}, },
}, },
create: function (context) { create: function (context) {
let documentImport = false let documentImportName
return { return {
ImportDeclaration(node) { ImportDeclaration(node) {
if (node.source.value === 'next/document') { if (node.source.value === 'next/document') {
if (node.specifiers.some(({ local }) => local.name === 'Document')) { const documentImport = node.specifiers.find(
documentImport = true ({ type }) => type === 'ImportDefaultSpecifier'
)
if (documentImport && documentImport.local) {
documentImportName = documentImport.local.name
} }
} }
}, },
...@@ -25,10 +28,10 @@ module.exports = { ...@@ -25,10 +28,10 @@ module.exports = {
(ancestorNode) => (ancestorNode) =>
ancestorNode.type === 'ClassDeclaration' && ancestorNode.type === 'ClassDeclaration' &&
ancestorNode.superClass && ancestorNode.superClass &&
ancestorNode.superClass.name === 'Document' ancestorNode.superClass.name === documentImportName
) )
if ((documentImport && documentClass) || node.name.name !== 'link') { if (documentClass || node.name.name !== 'link') {
return return
} }
......
...@@ -31,9 +31,9 @@ ruleTester.run('no-document-import-in-page', rule, { ...@@ -31,9 +31,9 @@ ruleTester.run('no-document-import-in-page', rule, {
filename: 'pages/_document.js', filename: 'pages/_document.js',
}, },
{ {
code: `import Document from "next/document" code: `import NextDocument from "next/document"
export default class MyDocument extends Document { export default class MyDocument extends NextDocument {
render() { render() {
return ( return (
<Html> <Html>
...@@ -58,6 +58,34 @@ ruleTester.run('no-document-import-in-page', rule, { ...@@ -58,6 +58,34 @@ ruleTester.run('no-document-import-in-page', rule, {
`, `,
filename: 'pages/_document.page.tsx', filename: 'pages/_document.page.tsx',
}, },
{
code: `import NDocument from "next/document"
export default class Document extends NDocument {
render() {
return (
<Html>
</Html>
);
}
}
`,
filename: 'pages/_document/index.js',
},
{
code: `import NDocument from "next/document"
export default class Document extends NDocument {
render() {
return (
<Html>
</Html>
);
}
}
`,
filename: 'pages/_document/index.tsx',
},
], ],
invalid: [ invalid: [
{ {
......
...@@ -114,5 +114,65 @@ ruleTester.run('no-head-import-in-document', rule, { ...@@ -114,5 +114,65 @@ ruleTester.run('no-head-import-in-document', rule, {
}, },
], ],
}, },
{
code: `
import Document, { Html, Main, NextScript } from 'next/document'
import Head from 'next/head'
class MyDocument extends Document {
render() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
}
export default MyDocument
`,
filename: 'pages/_document/index.js',
errors: [
{
message:
'next/head should not be imported in pages/_document/index.js. Import Head from next/document instead. See https://nextjs.org/docs/messages/no-head-import-in-document.',
type: 'ImportDeclaration',
},
],
},
{
code: `
import Document, { Html, Main, NextScript } from 'next/document'
import Head from 'next/head'
class MyDocument extends Document {
render() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
}
export default MyDocument
`,
filename: 'pages/_document/index.tsx',
errors: [
{
message:
'next/head should not be imported in pages/_document/index.tsx. Import Head from next/document instead. See https://nextjs.org/docs/messages/no-head-import-in-document.',
type: 'ImportDeclaration',
},
],
},
], ],
}) })
...@@ -26,13 +26,24 @@ ruleTester.run('no-page-custom-font', rule, { ...@@ -26,13 +26,24 @@ ruleTester.run('no-page-custom-font', rule, {
href="https://fonts.googleapis.com/css2?family=Krona+One&display=swap" href="https://fonts.googleapis.com/css2?family=Krona+One&display=swap"
rel="stylesheet" rel="stylesheet"
/> />
</Head>
</Html>
);
}
}
export default MyDocument;
`,
`import NextDocument, { Html, Head } from "next/document";
class Document extends NextDocument {
render() {
return (
<Html>
<Head>
<link <link
href={process.env.NEXT_PUBLIC_CANONICAL_URL} href="https://fonts.googleapis.com/css2?family=Krona+One&display=swap"
rel="canonical" rel="stylesheet"
/>
<link
href={new URL("../public/favicon.ico", import.meta.url).toString()}
rel="icon"
/> />
</Head> </Head>
</Html> </Html>
...@@ -40,7 +51,7 @@ ruleTester.run('no-page-custom-font', rule, { ...@@ -40,7 +51,7 @@ ruleTester.run('no-page-custom-font', rule, {
} }
} }
export default MyDocument; export default Document;
`, `,
], ],
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment