eslint-plugin-header

What is eslint-plugin-header?

The eslint-plugin-header package is an ESLint plugin that allows you to enforce consistent header comments in your JavaScript files. This can be useful for ensuring that all files in a project contain specific licensing information, author details, or any other required header content.

What are eslint-plugin-header's main functionalities?

Enforce Header Comments

This feature allows you to enforce a specific header comment at the top of your JavaScript files. The configuration specifies the type of comment (block in this case) and the content of the header.

module.exports = {
  "plugins": ["header"],
  "rules": {
    "header/header": [2, "block", [
      "*",
      " This is a header comment",
      " Author: Your Name",
      " License: MIT",
      "*/"
    ]]
  }
};

Customizable Header Content

You can customize the content of the header to include project-specific information such as the project name, author, and date. This ensures that all files have consistent and up-to-date header information.

module.exports = {
  "plugins": ["header"],
  "rules": {
    "header/header": [2, "block", [
      "*",
      " Project: My Project",
      " Author: Your Name",
      " Date: 2023-10-01",
      "*/"
    ]]
  }
};

Support for Different Comment Styles

The plugin supports different styles of comments, such as line comments. This allows you to choose the comment style that best fits your project's coding standards.

module.exports = {
  "plugins": ["header"],
  "rules": {
    "header/header": [2, "line", [
      "// This is a header comment",
      "// Author: Your Name",
      "// License: MIT"
    ]]
  }
};

Other packages similar to eslint-plugin-header

eslint-plugin-license-header

The eslint-plugin-license-header package is another ESLint plugin that enforces license headers in your files. It is similar to eslint-plugin-header but focuses specifically on license information. It allows for customizable license templates and supports various comment styles.

eslint-plugin-file-header

The eslint-plugin-file-header package is designed to enforce file headers in your JavaScript files. It offers similar functionality to eslint-plugin-header, allowing you to specify the content and format of the headers. It also supports placeholders for dynamic content such as the current date.

eslint-plugin-jsdoc

The eslint-plugin-jsdoc package is primarily focused on enforcing JSDoc comments in your code. While it is not specifically designed for file headers, it can be configured to ensure that certain JSDoc comments are present at the top of your files, providing similar functionality to eslint-plugin-header.

README

eslint-plugin-header

ESLint plugin to ensure that files begin with given comment.

Often you will want to have a copyright notice at the top of every file. This ESLint plugin checks that the first comment in every file has the contents defined in the rule settings.

Usage

This rule takes 1, 2 or 3 arguments with an optional settings object.

1 argument

In the 1 argument form the argument is the filename of a file that contains the comment(s) that should appear at the top of every file:

{
    "plugins": [
        "header"
    ],
    "rules": {
        "header/header": [2, "config/header.js"]
    }
}

config/header.js:

// Copyright 2015
// My company

Due to limitations in eslint plugins, the file is read relative to the working directory that eslint is executed in. If you run eslint from elsewhere in your tree then the header file will not be found.

2 arguments

In the 2 argument form the first must be either "block" or "line" to indicate what style of comment should be used. The second is either a string (including newlines) of the comment, or an array of each line of the comment.

{
    "plugins": [
        "header"
    ],
    "rules": {
        "header/header": [2, "block", "Copyright 2015\nMy Company"]
    }
}

3 arguments

The optional third argument which defaults to 1 specifies the number of newlines that are enforced after the header.

Zero newlines:

{
    "plugins": [
        "header"
    ],
    "rules": {
        "header/header": [2, "block", [" Copyright now","My Company "], 0]
    }
}

/* Copyright now
My Company */ console.log(1)

One newline (default)

{
    "plugins": [
        "header"
    ],
    "rules": {
        "header/header": [2, "block", [" Copyright now","My Company "], 1]
    }
}

/* Copyright now
My Company */
console.log(1)

two newlines

{
    "plugins": [
        "header"
    ],
    "rules": {
        "header/header": [2, "block", [" Copyright now","My Company "], 2]
    }
}

/* Copyright now
My Company */

console.log(1)

Regular expressions

Instead of a string to be checked for exact matching you can also supply a regular expression. Be aware that you have to escape backslashes:

{
    "plugins": [
        "header"
    ],
    "rules": {
        "header/header": [2, "block", [
            {"pattern": " Copyright \\d{4}"},
            "My Company"
        ]]
    }
}

This would match:

/* Copyright 2808
My Company*/

When you use a regular expression pattern, you can also provide a template property, to provide the comment value when using eslint --fix:

{
    "plugins": [
        "header"
    ],
    "rules": {
        "header/header": [2, "block", [
            {"pattern": " Copyright \\d{4}", "template": " Copyright 2019"}, 
            "My Company"
        ]]
    }
}

Line Endings

The rule works with both unix and windows line endings. For ESLint --fix, the rule will use the line ending format of the current operating system (via the node os package). This setting can be overwritten as follows:

"rules": {
    "header/header": [2, "block", ["Copyright 2018", "My Company"], {"lineEndings": "windows"}]
}

Possible values are unix for \n and windows for \r\n line endings.

Examples

The following examples are all valid.

"block", "Copyright 2015, My Company":

/*Copyright 2015, My Company*/
console.log(1);

"line", ["Copyright 2015", "My Company"]]:

//Copyright 2015
//My Company
console.log(1)

"line", [{pattern: "^Copyright \\d{4}$"}, {pattern: "^My Company$"}]]:

//Copyright 2017
//My Company
console.log(1)

With more decoration

"header/header": [2, "block", [
    "************************",
    " * Copyright 2015",
    " * My Company",
    " ************************"
]

/*************************
 * Copyright 2015
 * My Company
 *************************/
 console.log(1);

License

MIT