eslint-plugin-header

3.1.1 verified Sat Apr 25 auth: no javascript

ESLint plugin to enforce that files begin with a specific comment block, commonly used for copyright notices. The current stable version is 3.1.1, released in 2022. It supports line and block comments, regular expressions for flexible matching, and custom newline counts after the header. Unlike manual checks, it integrates with ESLint's autofix and is suitable for large codebases requiring consistent licensing headers. The package requires eslint >=7.7.0.

Common errors

error ESLint: Failed to load plugin 'header': Cannot find module 'eslint-plugin-header' ↓

cause The plugin is not installed in the project.

fix

Run npm install --save-dev eslint-plugin-header

error Configuration for rule "header/header" is invalid: Value "[2, "block", "Copyright ..."]" is not a valid severity. ↓

cause Using incorrect array syntax; first element is severity (2 or 'error'), but sometimes users mistakenly omit it.

fix

Use severity as first element: [2, "block", ...] or ["error", "block", ...]

error ESLint: The rule 'header/header' does not exist. ↓

cause The plugin is not registered in the 'plugins' array.

fix

Add "plugins": ["header"] to your eslint config.

Warnings

gotcha The header file path for 1-argument form is resolved relative to the current working directory, not the eslint config file location. ↓

fix Use absolute paths or ensure the working directory is where the header file resides.

deprecated The `lineEndings` option as a settings object in the rule arguments is deprecated in favor of ESLint's built-in line ending handling. ↓

fix Use `lineEndings` as a property in the rule options object; see documentation.

gotcha Regular expression patterns must have double-escaped backslashes (e.g., `\\d` for `\d`) when defined in JSON. ↓

fix Write patterns with double backslashes: `{"pattern": " Copyright \\d{4}"}`

gotcha The header comment must be the very first non-whitespace content; shebang lines are ignored. ↓

fix Ensure the header is the first comment; shebang lines (#!/usr/bin/env node) are allowed before the header.

Install

npm install eslint-plugin-header

yarn add eslint-plugin-header

pnpm add eslint-plugin-header

Imports

header
wrong
```
const header = require('eslint-plugin-header')
```
correct
```
import header from 'eslint-plugin-header'
```
The plugin is CommonJS-based but can be imported as default in ESM environments with bundlers like Webpack or Rollup.

Quickstart

Minimum configuration to enforce a block comment header with two lines.

// .eslintrc.json
{
  "plugins": ["header"],
  "rules": {
    "header/header": [2, "block", ["Copyright 2023", "My Company"]]
  }
}

// myfile.js (invalid)
console.log('missing header');

// Run ESLint
// npx eslint myfile.js
// Error: Missing header comment at top of file