Adds consistency to ESLint rules. (#34335)

* Adds consistency to ESLint rules. * Fixes lint errors. * Fixes manifest. * Adds missing title. * Fixes copy / paste error. Co-authored-by: Lee Robinson <me@leerob.io> * Update errors/no-script-in-document.md Co-authored-by: Lee Robinson <me@leerob.io> * Update errors/no-sync-scripts.md Co-authored-by: Lee Robinson <me@leerob.io> * Updates a couple of rule descriptions. * Adds redirects. * Fixes unit tests. * Removes duplicated section. * Updates `no-before-interactive-script-outside-document` description. * Fixes lint. * Fixes integration tests. * Adds description to `no-before-interactive-script-outside-document` documentation. * Removes `link-passhref` from rules list. * Updates remaining `pages/_middleware.js` references. * Adds consistancy to messaging in new `no-styled-jsx-in-document` rule. * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: Tim Neutkens <tim@timneutkens.nl> Co-authored-by: JJ Kasper <jj@jjsweb.site>
vercel · Jun 14, 2022 · 5211ac5 · 5211ac5
1 parent ec4df71
commit 5211ac5
Show file tree

Hide file tree

Showing 63 changed files with 445 additions and 338 deletions.
diff --git a/docs/basic-features/eslint.md b/docs/basic-features/eslint.md
@@ -80,28 +80,31 @@ This will take precedence over the configuration from `next.config.js`.
 
 Next.js provides an ESLint plugin, [`eslint-plugin-next`](https://www.npmjs.com/package/@next/eslint-plugin-next), already bundled within the base configuration that makes it possible 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](/docs/messages/google-font-display.md)               | Enforce optional or swap font-display behavior with Google Fonts                                                       |
-| ✔️  | [next/google-font-preconnect](/docs/messages/google-font-preconnect.md)         | Enforce preconnect usage with Google Fonts                                                                             |
-| ✔️  | [next/link-passhref](/docs/messages/link-passhref.md)                           | Enforce passHref prop usage with custom Link components                                                                |
-| ✔️  | [next/no-css-tags](/docs/messages/no-css-tags.md)                               | Prevent manual stylesheet tags                                                                                         |
-| ✔️  | [next/no-document-import-in-page](/docs/messages/no-document-import-in-page.md) | Disallow importing next/document outside of pages/document.js                                                          |
-| ✔️  | [next/no-head-import-in-document](/docs/messages/no-head-import-in-document.md) | Disallow importing next/head in pages/document.js                                                                      |
-| ✔️  | [next/no-html-link-for-pages](/docs/messages/no-html-link-for-pages.md)         | Prohibit HTML anchor links to pages without a Link component                                                           |
-| ✔️  | [next/no-img-element](/docs/messages/no-img-element.md)                         | Prohibit usage of HTML &lt;img&gt; element                                                                             |
-| ✔️  | [next/no-head-element](/docs/messages/no-head-element.md)                       | Prohibit usage of HTML &lt;head&gt; element                                                                            |
-| ✔️  | [next/no-page-custom-font](/docs/messages/no-page-custom-font.md)               | Prevent page-only custom fonts                                                                                         |
-| ✔️  | [next/no-sync-scripts](/docs/messages/no-sync-scripts.md)                       | Forbid synchronous scripts                                                                                             |
-| ✔️  | [next/no-title-in-document-head](/docs/messages/no-title-in-document-head.md)   | Disallow using &lt;title&gt; with Head from next/document                                                              |
-| ✔️  | [next/no-unwanted-polyfillio](/docs/messages/no-unwanted-polyfillio.md)         | Prevent duplicate polyfills from Polyfill.io                                                                           |
-| ✔️  | [next/inline-script-id](/docs/messages/inline-script-id.md)                     | Enforce id attribute on next/script components with inline content                                                     |
-| ✔️  | next/no-typos                                                                   | Ensure no typos were made declaring [Next.js's data fetching function](/docs/basic-features/data-fetching/overview.md) |
-| ✔️  | [next/next-script-for-ga](/docs/messages/next-script-for-ga.md)                 | Use the Script component to defer loading of the script until necessary.                                               |
-| ✔️  | [next/no-styled-jsx-in-document](/docs/messages/no-styled-jsx-in-document.md)   | styled-jsx should not be used in \_document                                                                            |
-
 - ✔: Enabled in the recommended configuration
 
+|     | Rule                                                                                                                        | Description                                                                                        |
+| :-: | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| ✔️  | [@next/next/google-font-display](/docs/messages/google-font-display.md)                                                     | Enforce font-display behavior with Google Fonts.                                                   |
+| ✔️  | [@next/next/google-font-preconnect](/docs/messages/google-font-preconnect.md)                                               | Ensure `preconnect` is used with Google Fonts.                                                     |
+| ✔️  | [@next/next/inline-script-id](/docs/messages/inline-script-id.md)                                                           | Enforce `id` attribute on `next/script` components with inline content.                            |
+| ✔️  | [@next/next/next-script-for-ga](/docs/messages/next-script-for-ga.md)                                                       | Prefer `next/script` component when using the inline script for Google Analytics.                  |
+| ✔️  | [@next/next/no-before-interactive-script-outside-document](/docs/messages/no-before-interactive-script-outside-document.md) | Prevent usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.     |
+| ✔️  | [@next/next/no-css-tags](/docs/messages/no-css-tags.md)                                                                     | Prevent manual stylesheet tags.                                                                    |
+| ✔️  | [@next/next/no-document-import-in-page](/docs/messages/no-document-import-in-page.md)                                       | Prevent importing `next/document` outside of `pages/_document.js`.                                 |
+| ✔️  | [@next/next/no-duplicate-head](/docs/messages/no-duplicate-head.md)                                                         | Prevent duplicate usage of `<Head>` in `pages/_document.js`.                                       |
+| ✔️  | [@next/next/no-head-element](/docs/messages/no-head-element.md)                                                             | Prevent usage of `<head>` element.                                                                 |
+| ✔️  | [@next/next/no-head-import-in-document](/docs/messages/no-head-import-in-document.md)                                       | Prevent usage of `next/head` in `pages/_document.js`.                                              |
+| ✔️  | [@next/next/no-html-link-for-pages](/docs/messages/no-html-link-for-pages.md)                                               | Prevent usage of `<a>` elements to navigate to internal Next.js pages.                             |
+| ✔️  | [@next/next/no-img-element](/docs/messages/no-img-element.md)                                                               | Prevent usage of `<img>` element to prevent layout shift.                                          |
+| ✔️  | [@next/next/no-page-custom-font](/docs/messages/no-page-custom-font.md)                                                     | Prevent page-only custom fonts.                                                                    |
+| ✔️  | [@next/next/no-script-component-in-head](/docs/messages/no-script-component-in-head.md)                                     | Prevent usage of `next/script` in `next/head` component.                                           |
+| ✔️  | [@next/next/no-server-import-in-page](/docs/messages/no-server-import-in-page.md)                                           | Prevent usage of `next/server` outside of `middleware.js`.                                         |
+| ✔️  | [@next/next/no-styled-jsx-in-document](/docs/messages/no-styled-jsx-in-document.md)                                         | Prevent usage of `styled-jsx` in `pages/_document.js`.                                             |
+| ✔️  | [@next/next/no-sync-scripts](/docs/messages/no-sync-scripts.md)                                                             | Prevent synchronous scripts.                                                                       |
+| ✔️  | [@next/next/no-title-in-document-head](/docs/messages/no-title-in-document-head.md)                                         | Prevent usage of `<title>` with `Head` component from `next/document`.                             |
+| ✔️  | @next/next/no-typos                                                                                                         | Prevent common typos in [Next.js's data fetching functions](/docs/basic-features/data-fetching.md) |
+| ✔️  | [@next/next/no-unwanted-polyfillio](/docs/messages/no-unwanted-polyfillio.md)                                               | Prevent duplicate polyfills from Polyfill.io.                                                      |
+
 If you already have ESLint configured in your application, we recommend extending from this plugin directly instead of including `eslint-config-next` unless a few conditions are met. Refer to the [Recommended Plugin Ruleset](/docs/basic-features/eslint.md#recommended-plugin-ruleset) to learn more.
 
 ### Custom Settings

diff --git a/errors/google-font-display.md b/errors/google-font-display.md
@@ -1,8 +1,10 @@
 # Google Font Display
 
+> Enforce font-display behavior with Google Fonts.
+
 ### Why This Error Occurred
 
-For a Google Font, the `display` descriptor was either not assigned or set to `auto`, `fallback`, or `block`.
+For a Google Font, the font-display descriptor was either missing or set to `auto`, `block`, or `fallback`, which are not recommended.
 
 ### Possible Ways to Fix It
 
@@ -29,9 +31,10 @@ Specifying `display=optional` minimizes the risk of invisible text or layout shi
 
 ### When Not To Use It
 
-If you want to specifically display a font using a `block` or `fallback` strategy, then you can disable this rule.
+If you want to specifically display a font using an `auto`, `block`, or `fallback` strategy, then you can disable this rule.
 
 ### Useful Links
 
+- [Controlling Font Performance with font-display](https://developer.chrome.com/blog/font-display/)
 - [Google Fonts API Docs](https://developers.google.com/fonts/docs/css2#use_font-display)
 - [CSS `font-display` property](https://www.w3.org/TR/css-fonts-4/#font-display-desc)
diff --git a/errors/google-font-preconnect.md b/errors/google-font-preconnect.md
@@ -1,5 +1,7 @@
 # Google Font Preconnect
 
+> Ensure `preconnect` is used with Google Fonts.
+
 ### Why This Error Occurred
 
 A preconnect resource hint was not used with a request to the Google Fonts domain. Adding `preconnect` is recommended to initiate an early connection to the origin.

diff --git a/errors/inline-script-id.md b/errors/inline-script-id.md
@@ -1,4 +1,6 @@
-# next/script components with inline content require an `id` attribute
+# Inline script id
+
+> Enforce `id` attribute on `next/script` components with inline content.
 
 ## Why This Error Occurred
 

diff --git a/errors/link-passhref.md b/errors/link-passhref.md
@@ -1,4 +1,6 @@
-# Link passHref
+# Link `passHref`
+
+> Ensure `passHref` is used with custom `Link` components.
 
 ### Why This Error Occurred
 

diff --git a/errors/manifest.json b/errors/manifest.json
@@ -563,16 +563,34 @@
           "path": "/errors/sharp-version-avif.md"
         },
         {
-          "title": "script-in-document-page",
-          "path": "/errors/no-script-in-document-page.md"
+          "path": "/errors/no-script-in-document-page.md",
+          "redirect": {
+            "destination": "/errors/no-script-in-document"
+          }
+        },
+        {
+          "title": "no-script-in-document",
+          "path": "/errors/no-script-in-document.md"
         },
         {
           "title": "before-interactive-script-outside-document",
           "path": "/errors/no-before-interactive-script-outside-document.md"
         },
         {
-          "title": "script-component-in-head-component",
-          "path": "/errors/no-script-component-in-head-component.md"
+          "path": "/errors/no-script-in-head-component.md",
+          "redirect": {
+            "destination": "/errors/no-script-component-in-head"
+          }
+        },
+        {
+          "path": "/errors/no-script-component-in-head-component.md",
+          "redirect": {
+            "destination": "/errors/no-script-component-in-head"
+          }
+        },
+        {
+          "title": "no-script-component-in-head",
+          "path": "/errors/no-script-component-in-head.md"
         },
         {
           "title": "script-tags-in-head-component",

diff --git a/errors/next-script-for-ga.md b/errors/next-script-for-ga.md
@@ -1,5 +1,7 @@
 # Next Script for Google Analytics
 
+> Prefer `next/script` component when using the inline script for Google Analytics.
+
 ### Why This Error Occurred
 
 An inline script was used for Google analytics which might impact your webpage's performance.

diff --git a/errors/no-before-interactive-script-outside-document.md b/errors/no-before-interactive-script-outside-document.md
@@ -1,15 +1,17 @@
-# beforeInteractive Script component outside \_document.js
+# No Before Interactive Script Outside Document
+
+> Prevent usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.
 
 #### Why This Error Occurred
 
-You can't use the `next/script` component with the `beforeInteractive` strategy outside the `_document.js` page. That's because `beforeInteractive` strategy only works inside **\_document.js** and is designed to load scripts that are needed by the entire site (i.e. the script will load when any page in the application has been loaded server-side).
+You cannot use the `next/script` component with the `beforeInteractive` strategy outside `pages/_document.js`. That's because `beforeInteractive` strategy only works inside **`pages/_document.js`** and is designed to load scripts that are needed by the entire site (i.e. the script will load when any page in the application has been loaded server-side).
 
 #### Possible Ways to Fix It
 
-If you want a global script, move the script inside `_document.js` page.
+If you want a global script, move the script inside `pages/_document.js`.
 
 ```jsx
-// In _document.js
+// In `pages/_document.js`
 import { Html, Head, Main, NextScript } from 'next/document'
 import Script from 'next/script'
 

diff --git a/errors/no-css-tags.md b/errors/no-css-tags.md
@@ -1,8 +1,10 @@
 # No CSS Tags
 
+> Prevent manual stylesheet tags.
+
 ### Why This Error Occurred
 
-An HTML link element was used to link to an external stylesheet. This can negatively affect CSS resource loading on your web page.
+A `link` element was used to link to an external stylesheet. This can negatively affect CSS resource loading on your webpage.
 
 ### Possible Ways to Fix It
 

diff --git a/errors/no-document-import-in-page.md b/errors/no-document-import-in-page.md
@@ -1,5 +1,7 @@
 # No Document Import in Page
 
+> Prevent importing `next/document` outside of `pages/_document.js`.
+
 ### Why This Error Occurred
 
 `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.

diff --git a/errors/no-duplicate-head.md b/errors/no-duplicate-head.md
@@ -1,5 +1,7 @@
 # No Duplicate Head
 
+> Prevent duplicate usage of `<Head>` in `pages/_document.js`.
+
 ### Why This Error Occurred
 
 More than a single instance of the `<Head />` component was used in a single custom document. This can cause unexpected behavior in your application.

diff --git a/errors/no-head-element.md b/errors/no-head-element.md
@@ -1,8 +1,10 @@
 # No Head Element
 
+> Prevent usage of `<head>` element.
+
 ### Why This Error Occurred
 
-An HTML `<head>` element was used to include page-level metadata, but this can cause unexpected behavior in a Next.js application. Use Next.js' built-in `<Head />` component instead.
+A `<head>` element was used to include page-level metadata, but this can cause unexpected behavior in a Next.js application. Use Next.js' built-in `next/head` component instead.
 
 ### Possible Ways to Fix It
 

diff --git a/errors/no-head-import-in-document.md b/errors/no-head-import-in-document.md
@@ -1,5 +1,7 @@
 # No Head Import in Document
 
+> Prevent usage of `next/head` in `pages/_document.js`.
+
 ### Why This Error Occurred
 
 `next/head` was imported in `pages/_document.js`. This can cause unexpected issues in your application.

diff --git a/errors/no-html-link-for-pages.md b/errors/no-html-link-for-pages.md
@@ -1,8 +1,10 @@
 # No HTML link for pages
 
+> Prevent usage of `<a>` elements to navigate to internal Next.js pages.
+
 ### Why This Error Occurred
 
-An HTML anchor element, `<a>`, was used to navigate to a page route without using the `Link` component.
+An `<a>` element was used to navigate to a page route without using the `next/link` component, causing unnecessary full page refreshes.
 
 The `Link` component is required in order to enable client-side route transitions between pages and provide a single-page app experience.
 

diff --git a/errors/no-img-element.md b/errors/no-img-element.md
@@ -1,8 +1,10 @@
 # No Img Element
 
+> Prevent usage of `<img>` element to prevent layout shift.
+
 ### Why This Error Occurred
 
-An HTML `<img>` element was used to display an image. For better performance and automatic Image Optimization, use Next.js' built-in image component instead.
+An `<img>` element was used to display an image. For better performance and automatic Image Optimization, use `next/image` instead.
 
 ### Possible Ways to Fix It
 

diff --git a/errors/no-page-custom-font.md b/errors/no-page-custom-font.md
@@ -1,9 +1,11 @@
 # No Page Custom Font
 
+> Prevent page-only custom fonts.
+
 ### Why This Error Occurred
 
 - The custom font you're adding was added to a page - this only adds the font to the specific page and not the entire application.
-- The custom font you're adding was added to a separate component within `Document` - this disables automatic font optimization.
+- The custom font you're adding was added to a separate component within `pages/_document.js` - this disables automatic font optimization.
 
 ### Possible Ways to Fix It
 

diff --git a/.../no-script-component-in-head-component.md → errors/no-script-component-in-head.md b/.../no-script-component-in-head-component.md → errors/no-script-component-in-head.md
@@ -1,12 +1,14 @@
-# Script component inside Head component
+# No Script Component in Head
+
+> Prevent usage of `next/script` in `next/head` component.
 
 #### Why This Error Occurred
 
-The `next/script` component shouldn't be placed inside the `next/head` component
+The `next/script` component should not be used in a `next/head` component.
 
 #### Possible Ways to Fix It
 
-Move the `<Script />` component outside of `<Head>...</Head>`
+Move the `<Script />` component outside of `<Head>` instead.
 
 **Before**
 

diff --git a/errors/no-script-in-document-page.md b/errors/no-script-in-document-page.md