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

Document & Head Management Rules

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

ESLint rules for proper Next.js document structure and head element management. These rules ensure correct usage of Next.js Head component and proper document architecture patterns.

Capabilities

no-head-element

Prevents HTML head elements in favor of Next.js Head component for better SSR and hydration.

/**
 * Rule: no-head-element
 * Prevents HTML head elements, promotes Next.js Head component
 * Severity: warn (in recommended config)
 * Category: Document Structure
 */
interface NoHeadElementRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent usage of HTML head element';
      category: 'Document Structure';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Head content uses Next.js Head component Prevents: Direct HTML head manipulation that breaks SSR

no-head-import-in-document

Prevents Head component import in _document.js files where it shouldn't be used.

/**
 * Rule: no-head-import-in-document
 * Prevents Head import in _document.js files
 * Severity: error (in recommended config)
 * Category: Document Structure
 */
interface NoHeadImportInDocumentRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent Head import in _document.js';
      category: 'Document Structure';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Head component is not imported in _document.js files Prevents: Incorrect Head usage that can cause hydration issues

no-document-import-in-page

Prevents Document component import in page files where it's not appropriate.

/**
 * Rule: no-document-import-in-page
 * Prevents Document import in page files
 * Severity: error (in recommended config)
 * Category: Document Structure
 */
interface NoDocumentImportInPageRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent Document import in page files';
      category: 'Document Structure';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Document component is only used in _document.js Prevents: Incorrect Document usage that breaks Next.js architecture

no-duplicate-head

Prevents multiple Head components in the same file to avoid conflicts.

/**
 * Rule: no-duplicate-head
 * Prevents multiple Head components in same file
 * Severity: error (in recommended config)
 * Category: Document Structure
 */
interface NoDuplicateHeadRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent duplicate Head components';
      category: 'Document Structure';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Only one Head component per file Prevents: Conflicting head content and hydration issues

no-title-in-document-head

Prevents title elements in _document.js Head component where they're ineffective.

/**
 * Rule: no-title-in-document-head
 * Prevents title in _document.js Head component
 * Severity: warn (in recommended config)
 * Category: Document Structure
 */
interface NoTitleInDocumentHeadRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent title in _document.js Head';
      category: 'Document Structure';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: Title elements are not in _document.js Head Prevents: Ineffective title tags that don't work in _document

no-styled-jsx-in-document

Prevents styled-jsx usage in _document.js where it can cause issues.

/**
 * Rule: no-styled-jsx-in-document
 * Prevents styled-jsx in _document.js files
 * Severity: warn (in recommended config)
 * Category: Document Structure
 */
interface NoStyledJsxInDocumentRule extends Rule.RuleModule {
  meta: {
    docs: {
      description: 'Prevent styled-jsx in _document.js';
      category: 'Document Structure';
      recommended: true;
      url: string;
    };
    type: 'problem';
    schema: [];
  };
}

Validates: styled-jsx is not used in _document.js files Prevents: Styling issues and hydration problems in document structure

Usage Examples

Correct Head Usage

// ✅ Correct - Using Next.js Head component in pages
import Head from 'next/head';

export default function MyPage() {
  return (
    <>
      <Head>
        <title>My Page Title</title>
        <meta name="description" content="Page description" />
      </Head>
      <div>Page content</div>
    </>
  );
}

Correct Document Structure

// ✅ Correct - _document.js structure
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head>
        {/* Global meta tags, fonts, analytics - NO title tags */}
        <link rel="preconnect" href="https://fonts.googleapis.com" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Document Rules Configuration

// Focus on document structure validation
module.exports = {
  plugins: ['@next/next'],
  rules: {
    // Critical document structure rules as errors
    '@next/next/no-head-import-in-document': 'error',
    '@next/next/no-document-import-in-page': 'error',
    '@next/next/no-duplicate-head': 'error',
    
    // Best practice rules as warnings
    '@next/next/no-head-element': 'warn',
    '@next/next/no-title-in-document-head': 'warn',
    '@next/next/no-styled-jsx-in-document': 'warn',
  },
};

Rule Categories

Component Separation: no-head-import-in-document, no-document-import-in-page
Content Management: no-duplicate-head, no-title-in-document-head
Best Practices: no-head-element, no-styled-jsx-in-document