tessl/npm-next--eslint-plugin-next

ESLint plugin for Next.js with 21 rules enforcing best practices and Core Web Vitals optimization.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Script & Asset Management Rules

Name: tessl/npm-next--eslint-plugin-next
Author: tessl

ESLint rules for proper script loading and asset management in Next.js applications. These rules ensure optimal script placement, loading strategies, and prevent common script-related performance issues.

Capabilities

inline-script-id

Enforces id attribute for inline scripts to enable proper CSP and security practices.

/**
 * Rule: inline-script-id
 * Enforces id attribute for inline scripts
 * Severity: error (in recommended config)
 * Category: Security/Scripts
 */
interface InlineScriptIdRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Enforce id attribute for inline scripts';
      category: 'Security';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Inline script elements have id attributes Prevents: CSP violations and security issues with inline scripts

next-script-for-ga

Enforces Next.js Script component for Google Analytics instead of HTML script tags.

/**
 * Rule: next-script-for-ga
 * Enforces Next.js Script component for Google Analytics
 * Severity: warn (in recommended config)
 * Category: Performance/Scripts
 */
interface NextScriptForGARule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Enforce Next.js Script component for Google Analytics';
      category: 'Performance';
      recommended: true;
      url: string;
    };
    type: 'suggestion';
    schema: [];
  };
}

Validates: Google Analytics uses Next.js Script component Prevents: Suboptimal loading strategies for analytics scripts

no-before-interactive-script-outside-document

Prevents beforeInteractive scripts outside of _document.js where they won't work correctly.

/**
 * Rule: no-before-interactive-script-outside-document
 * Prevents beforeInteractive scripts outside _document.js
 * Severity: warn (in recommended config)
 * Category: Scripts/Architecture
 */
interface NoBeforeInteractiveScriptOutsideDocumentRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent beforeInteractive scripts outside _document.js';
      category: 'Architecture';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: beforeInteractive scripts are only in _document.js Prevents: Scripts that won't load with correct timing strategy

no-script-component-in-head

Prevents Script components inside Head components where they're ineffective.

/**
 * Rule: no-script-component-in-head
 * Prevents Script components in Head components
 * Severity: error (in recommended config)
 * Category: Scripts/Architecture
 */
interface NoScriptComponentInHeadRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent Script components in Head';
      category: 'Architecture';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Script components are not placed inside Head components Prevents: Scripts that won't execute due to incorrect placement

no-unwanted-polyfillio

Prevents unwanted polyfill.io usage that can introduce security and performance issues.

/**
 * Rule: no-unwanted-polyfillio
 * Prevents unwanted polyfill.io usage
 * Severity: warn (in recommended config)
 * Category: Security/Performance
 */
interface NoUnwantedPolyfillIoRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent unwanted polyfill.io usage';
      category: 'Security';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Polyfill.io scripts are not used without justification Prevents: Potential security and performance issues from third-party polyfills

no-css-tags

Prevents manual CSS link tags in favor of Next.js CSS import system.

/**
 * Rule: no-css-tags
 * Prevents manual CSS link tags
 * Severity: warn (in recommended config)
 * Category: Assets/Performance
 */
interface NoCssTagsRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent manual CSS link tags';
      category: 'Performance';
      recommended: true;
      url: string;
    };
    type: 'suggestion';
    schema: [];
  };
}

Validates: CSS is loaded through Next.js import system Prevents: Suboptimal CSS loading and missing optimizations

Usage Examples

Correct Script Usage

// ✅ Correct - Using Next.js Script component
import Script from 'next/script';

export default function MyPage() {
  return (
    <>
      <div>Page content</div>
      
      {/* Google Analytics with Next.js Script */}
      <Script
        src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
        strategy="afterInteractive"
      />
      <Script id="google-analytics" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', 'GA_MEASUREMENT_ID');
        `}
      </Script>
    </>
  );
}

Correct Document Scripts

// ✅ Correct - beforeInteractive scripts in _document.js
import { Html, Head, Main, NextScript } from 'next/document';
import Script from 'next/script';

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
        
        {/* Critical scripts that need to load before interactivity */}
        <Script
          id="critical-script"
          strategy="beforeInteractive"
          src="/critical-script.js"
        />
      </body>
    </Html>
  );
}

Correct CSS Loading

// ✅ Correct - CSS through Next.js import system
import styles from './MyComponent.module.css';
import 'global-styles.css';

export default function MyComponent() {
  return <div className={styles.container}>Content</div>;
}

Script Rules Configuration

// Focus on script management and security
module.exports = {
  plugins: ['@next/next'],
  rules: {
    // Critical script placement rules as errors
    '@next/next/inline-script-id': 'error',
    '@next/next/no-script-component-in-head': 'error',
    
    // Best practice rules as warnings
    '@next/next/next-script-for-ga': 'warn',
    '@next/next/no-before-interactive-script-outside-document': 'warn',
    '@next/next/no-unwanted-polyfillio': 'warn',
    '@next/next/no-css-tags': 'warn',
  },
};

Script Loading Strategies

Available Strategies

beforeInteractive: Load before page becomes interactive (only in _document.js)
afterInteractive: Load after page becomes interactive
lazyOnload: Load during browser idle time
worker: Load in a web worker (experimental)

Strategy Guidelines

Use beforeInteractive for critical scripts that must load early
Use afterInteractive for analytics and non-critical functionality
Use lazyOnload for scripts that can be deferred
Always specify a strategy explicitly

Rule Categories

Security: inline-script-id, no-unwanted-polyfillio
Performance: next-script-for-ga, no-css-tags
Architecture: no-before-interactive-script-outside-document, no-script-component-in-head