\n\n\n\nA [stylelint](https://github.com/stylelint/stylelint) custom rule that asserts every file begins with a configured header comment — typically a copyright or licence notice. When the header is missing, the rule reports an error; with `--fix`, it prepends the header for you.\n\n## The problem\n\nCopyright and licence headers are easy to add and easy to forget. A pre-commit lint check is the natural place to enforce them, but stylelint doesn't ship a header rule out of the box. **stylelint-header bridges the gap** — point it at a string or a file and every CSS/SCSS/Less file in your project picks up the same header, formatted consistently, with `--fix` doing the boring work.\n\n## Features\n\n- **Template-driven** — pass a string or a path to a file; supports [`lodash.template`](https://lodash.com/docs/4.17.15#template) syntax for variables\n- **Fuzzy matching** — uses [`string-similarity`](https://www.npmjs.com/package/string-similarity) so cosmetic edits (whitespace, year bumps) don't trigger false positives\n- **Auto-fixable** — missing headers are prepended on `--fix`, preserving the rest of the file\n- **Minifier-friendly** — opt into `/*!` syntax so the header survives tools like cssnano\n- **Built-in variables** — `YEAR`, `FILE_NAME`, and `FILE_PATH` are filled in automatically; bring your own as needed\n\n## Installation\n\n```sh\nyarn add --dev @allons-y/stylelint-header\nnpm install --save-dev @allons-y/stylelint-header\npnpm add --save-dev @allons-y/stylelint-header\nbun add --dev @allons-y/stylelint-header\n```\n\n## Usage\n\nAdd the plugin to your stylelint config and enable the `header/header` rule, passing either a string template or a path to a file containing the template. To toggle the rule off, set the value to `null`.\n\n### With a template file\n\n```json\n{\n\t\"plugins\": [\"@allons-y/stylelint-header\"],\n\t\"rules\": {\n\t\t\"header/header\": [\"./COPYRIGHT\"]\n\t}\n}\n```\n\n### With an inline template string\n\n```js\n{\n \"plugins\": [\"@allons-y/stylelint-header\"],\n \"rules\": {\n \"header/header\": [\n \"Copyright <%= YEAR %>. <%= company %>\",\n {\n templateVariables: {\n company: \"AI Overlords Inc.\",\n },\n nonMatchingTolerance: 0.8,\n },\n ],\n },\n}\n```\n\n## Options\n\n### `templateVariables`\n\n**Type:** `object` **Default:** `{}`\n\nKey/value pairs used to substitute variables in the header template. Given a template like:\n\n```js\n(c) <%= YEAR %> <%= company %>\n```\n\nand a config of:\n\n```js\n{\n templateVariables: {\n company: \"AI Overlords Inc.\",\n },\n}\n```\n\nthe resulting header becomes:\n\n```css\n/*!\n * (c) 2026 AI Overlords Inc.\n */\n```\n\n`YEAR` was substituted automatically — it doesn't need to appear in `templateVariables`. The following variables are always available:\n\n| Variable | Value |\n| ----------- | -------------------------------- |\n| `YEAR` | The current year |\n| `FILE_NAME` | The basename of the linted file |\n| `FILE_PATH` | The directory of the linted file |\n\nTemplates use [`lodash.template`](https://lodash.com/docs/4.17.15#template) — see the lodash docs for the full syntax.\n\n### `nonMatchingTolerance`\n\n**Type:** `number` between `0` and `1` **Default:** `0.98`\n\nMinimum similarity (per [`string-similarity`](https://www.npmjs.com/package/string-similarity)) between the comment found at the top of the file and the configured header. Lower the value when you want to allow small drift (e.g. a stale year); raise it to enforce an exact match.\n\n### `isRemovable`\n\n**Type:** `boolean` **Default:** `false`\n\nWhen `true`, generated headers begin with `/*` rather than `/*!`. The `/*!` prefix is preserved by most CSS minifiers (e.g. cssnano) — leave the default in place if you want the header to survive minification, set to `true` if you don't.\n\n## Requirements\n\n- Node.js >= 24\n- stylelint 17.x\n\n## Contributing\n\nContributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow, and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for community expectations. For bugs and ideas, please open an [issue](https://github.com/allonsy-studio/stylelint-header/issues/new).\n\n\n\n\n
License
\n\nThis project is licensed under the MPL-2.0 License - see the [LICENSE](LICENSE) file for details. This means you can use this freely, modify as needed; changes to MPL-licensed files should be shared back under the same license.\n\n\n\n\n\n\n
Funding ☕️
\n\nIf you find this plugin useful and would like to buy me a coffee/beer as a small thank you, I would greatly appreciate it!\n\n\n \n\n\n\n\n\n\n\n
![\"Brought](\"https://raw.githubusercontent.com/allonsy-studio/.github/main/assets/png/oss-banner.png\")
\n\n![\"\"](\"https://github.com/allonsy-studio/.github/blob/main/assets/tag-rule.gif\")
\n![\"Tests\"](\"https://github.com/allonsy-studio/stylelint-header/actions/workflows/testing.yml/badge.svg?branch=main\"){kind=icon}
\n \n \n ![\"NPM](\"https://img.shields.io/npm/v/@allons-y/stylelint-header.svg\")
\n \n \n ![\"License\"](\"https://img.shields.io/github/license/allonsy-studio/stylelint-header.svg\")
\n \n \n ![\"Brought](\"https://github.com/allonsy-studio/.github/blob/main/assets/svg/badge.svg\"){kind=icon}
\n \n![\"Buy](\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\")
\n\n\n\n\n\n\n\n\n\n\n","readmeFilename":"README.md"}![\"Brought](\"https://raw.githubusercontent.com/allonsy-studio/.github/main/assets/png/oss-footer-light.png\")
\n