docs(linter): update missing linter rule documentation (oxc-project#11190)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: amandesai01

crates/oxc_linter/src/rules/nextjs/inline_script_id.rs

@@ -23,18 +23,71 @@ pub struct InlineScriptId;
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Enforces that all `next/script` components with inline content or `dangerouslySetInnerHTML` must have an `id` prop.
     ///
     /// ### Why is this bad?
     ///
+    /// Next.js requires a unique `id` prop for inline scripts to properly deduplicate them during page renders.
+    /// Without an `id`, the same inline script might be executed multiple times, leading to unexpected behavior
+    /// or performance issues. This is particularly important for scripts that modify global state or perform
+    /// one-time initializations.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
+    /// import Script from 'next/script';
+    ///
+    /// export default function Page() {
+    ///   return (
+    ///     <Script>
+    ///       {`console.log('Hello world');`}
+    ///     </Script>
+    ///   );
+    /// }
+    ///
+    /// // Also incorrect with dangerouslySetInnerHTML
+    /// export default function Page() {
+    ///   return (
+    ///     <Script
+    ///       dangerouslySetInnerHTML={{
+    ///         __html: `console.log('Hello world');`
+    ///       }}
+    ///     />
+    ///   );
+    /// }
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```javascript
+    /// import Script from 'next/script';
+    ///
+    /// export default function Page() {
+    ///   return (
+    ///     <Script id="my-script">
+    ///       {`console.log('Hello world');`}
+    ///     </Script>
+    ///   );
+    /// }
+    ///
+    /// // Correct with dangerouslySetInnerHTML
+    /// export default function Page() {
+    ///   return (
+    ///     <Script
+    ///       id="my-script"
+    ///       dangerouslySetInnerHTML={{
+    ///         __html: `console.log('Hello world');`
+    ///       }}
+    ///     />
+    ///   );
+    /// }
+    ///
+    /// // No id required for external scripts
+    /// export default function Page() {
+    ///   return (
+    ///     <Script src="https://example.com/script.js" />
+    ///   );
+    /// }
     /// ```
     InlineScriptId,
     nextjs,

crates/oxc_linter/src/rules/nextjs/next_script_for_ga.rs

@@ -30,18 +30,53 @@ pub struct NextScriptForGa;
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Enforces the use of the `next/script` component when implementing Google Analytics in Next.js applications,
+    /// instead of using regular `<script>` tags.
     ///
     /// ### Why is this bad?
     ///
+    /// Using regular `<script>` tags for Google Analytics can lead to several issues:
+    /// - Scripts may load in a blocking manner, impacting page performance
+    /// - No built-in optimization or loading strategies
+    /// - Lack of automatic resource handling that Next.js provides
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
-    /// ```javascript
+    /// ```jsx
+    /// // Using regular script tag with GA source
+    /// <script src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
+    ///
+    /// // Using inline script for GA initialization
+    /// <script dangerouslySetInnerHTML={{
+    ///   __html: `
+    ///     window.dataLayer = window.dataLayer || [];
+    ///     function gtag(){dataLayer.push(arguments);}
+    ///     gtag('js', new Date());
+    ///     gtag('config', 'GA_MEASUREMENT_ID');
+    ///   `
+    /// }} />
     /// ```
     ///
     /// Examples of **correct** code for this rule:
-    /// ```javascript
+    /// ```jsx
+    /// import Script from 'next/script'
+    ///
+    /// // Using next/script for GA source
+    /// <Script
+    ///   src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
+    ///   strategy="lazyOnload"
+    /// />
+    ///
+    /// // Using next/script for GA initialization
+    /// <Script id="google-analytics">
+    ///   {`
+    ///     window.dataLayer = window.dataLayer || [];
+    ///     function gtag(){dataLayer.push(arguments);}
+    ///     gtag('js', new Date());
+    ///     gtag('config', 'GA_MEASUREMENT_ID');
+    ///   `}
+    /// </Script>
     /// ```
     NextScriptForGa,
     nextjs,

crates/oxc_linter/src/rules/nextjs/no_assign_module_variable.rs

@@ -17,18 +17,43 @@ pub struct NoAssignModuleVariable;
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Prevents the assignment or declaration of variables named `module` in Next.js applications.
     ///
     /// ### Why is this bad?
     ///
+    /// The variable name `module` is reserved in Next.js for internal use and module system
+    /// functionality. Declaring your own `module` variable can conflict with Next.js's internal
+    /// module system, lead to unexpected behavior in your application, and cause issues with code
+    /// splitting and hot module replacement.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
+    /// // Declaring module variable
+    /// let module = {};
+    ///
+    /// // Using module in variable declaration
+    /// const module = {
+    ///   exports: {}
+    /// };
+    ///
+    /// // Assigning to module
+    /// module = { id: 'my-module' };
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```javascript
+    /// // Use a different variable name
+    /// let myModule = {};
+    ///
+    /// // Use a more descriptive name
+    /// const customModule = {
+    ///   exports: {}
+    /// };
+    ///
+    /// // Access actual module object (when available)
+    /// console.log(module.exports);
     /// ```
     NoAssignModuleVariable,
     nextjs,

crates/oxc_linter/src/rules/nextjs/no_async_client_component.rs

@@ -20,18 +20,68 @@ pub struct NoAsyncClientComponent;
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Prevents the use of async functions for client components in Next.js applications.
+    /// This rule checks for any async function that:
+    /// - Is marked with "use client" directive
+    /// - Has a name starting with an uppercase letter (indicating it's a component)
+    /// - Is either exported as default or assigned to a variable
     ///
     /// ### Why is this bad?
     ///
+    /// Using async functions for client components can cause hydration mismatches between server and client,
+    /// can break component rendering lifecycle, and can lead to unexpected behavior with React's concurrent features.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
+    /// "use client"
+    ///
+    /// // Async component with default export
+    /// export default async function MyComponent() {
+    ///   return <></>
+    /// }
+    ///
+    /// // Async component with named export
+    /// async function MyComponent() {
+    ///   return <></>
+    /// }
+    /// export default MyComponent
+    ///
+    /// // Async arrow function component
+    /// const MyComponent = async () => {
+    ///   return <></>
+    /// }
+    /// export default MyComponent
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```javascript
+    /// "use client"
+    ///
+    /// // Regular synchronous component
+    /// export default function MyComponent() {
+    ///   return <></>
+    /// }
+    ///
+    /// // Handling async operations in effects
+    /// export default function MyComponent() {
+    ///   useEffect(() => {
+    ///     async function fetchData() {
+    ///       // async operations here
+    ///     }
+    ///     fetchData();
+    ///   }, []);
+    ///   return <></>
+    /// }
+    ///
+    /// // Async operations in event handlers
+    /// export default function MyComponent() {
+    ///   const handleClick = async () => {
+    ///     // async operations here
+    ///   }
+    ///   return <button onClick={handleClick}>Click me</button>
+    /// }
     /// ```
     NoAsyncClientComponent,
     nextjs,

crates/oxc_linter/src/rules/nextjs/no_before_interactive_script_outside_document.rs

@@ -25,19 +25,63 @@ pub struct NoBeforeInteractiveScriptOutsideDocument;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Prevent usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.
+    /// Prevents the usage of `next/script`'s `beforeInteractive` strategy outside of `pages/_document.js`.
+    /// This rule ensures that scripts with the `beforeInteractive` loading strategy are only used in the
+    /// document component where they are most effective.
     ///
     /// ### Why is this bad?
     ///
+    /// The `beforeInteractive` strategy is specifically designed to load scripts before any page hydration
+    /// occurs, which is only guaranteed to work correctly when placed in `pages/_document.js`. Using it elsewhere:
+    /// - May not achieve the intended early loading behavior
+    /// - Can lead to inconsistent script loading timing
+    /// - Might cause hydration mismatches or other runtime issues
+    /// - Could impact the application's performance optimization
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
-    /// ```javascript
+    /// ```jsx
+    /// // pages/index.js
+    /// import Script from 'next/script'
+    ///
+    /// export default function HomePage() {
+    ///   return (
+    ///     <div>
+    ///       <Script
+    ///         src="https://example.com/script.js"
+    ///         strategy="beforeInteractive"  // ❌ Wrong placement
+    ///       />
+    ///     </div>
+    ///   )
+    /// }
     /// ```
     ///
     /// Examples of **correct** code for this rule:
-    /// ```javascript
+    /// ```jsx
+    /// // pages/_document.js
+    /// import Document, { Html, Head, Main, NextScript } from 'next/document'
+    /// import Script from 'next/script'
+    ///
+    /// class MyDocument extends Document {
+    ///   render() {
+    ///     return (
+    ///       <Html>
+    ///         <Head />
+    ///         <body>
+    ///           <Script
+    ///             src="https://example.com/script.js"
+    ///             strategy="beforeInteractive"  // ✅ Correct placement
+    ///           />
+    ///           <Main />
+    ///           <NextScript />
+    ///         </body>
+    ///       </Html>
+    ///     )
+    ///   }
+    /// }
+    ///
+    /// export default MyDocument
     /// ```
     NoBeforeInteractiveScriptOutsideDocument,
     nextjs,

crates/oxc_linter/src/rules/nextjs/no_css_tags.rs

@@ -20,18 +20,48 @@ pub struct NoCssTags;
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Prevents manual inclusion of stylesheets using `<link>` tags in Next.js applications.
+    /// This rule checks for `<link>` tags with `rel="stylesheet"` that reference local CSS files.
     ///
     /// ### Why is this bad?
     ///
+    /// Next.js handles CSS imports automatically through its built-in CSS support.
+    /// Manual stylesheet inclusion bypasses Next.js's built-in CSS optimization,
+    /// prevents proper code splitting and optimization of styles, and may cause
+    /// Flash of Unstyled Content (FOUC). This also breaks automatic CSS hot reloading
+    /// during development.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
-    /// ```javascript
+    /// ```jsx
+    /// // Manually including local CSS file
+    /// <link href="/_next/static/css/styles.css" rel="stylesheet" />
+    ///
+    /// // In pages/_document.js
+    /// <Head>
+    ///   <link href="css/my-styles.css" rel="stylesheet" />
+    /// </Head>
     /// ```
     ///
     /// Examples of **correct** code for this rule:
-    /// ```javascript
+    /// ```jsx
+    /// // Importing CSS file directly
+    /// import '../styles/global.css'
+    ///
+    /// // Using CSS Modules
+    /// import styles from './Button.module.css'
+    ///
+    /// // Using external stylesheets (allowed)
+    /// <link
+    ///   href="https://fonts.googleapis.com/css?family=Open+Sans"
+    ///   rel="stylesheet"
+    /// />
+    ///
+    /// // Using styled-jsx
+    /// <style jsx>{`
+    ///   .button { color: blue; }
+    /// `}</style>
     /// ```
     NoCssTags,
     nextjs,