lint-staged

What is lint-staged?

The lint-staged npm package is used to run linters on staged git files. It allows you to run specific commands before committing, ensuring that only clean, linted code gets committed to your repository. This helps in maintaining code quality and reducing the chances of committing code with errors or that doesn't adhere to the project's coding standards.

What are lint-staged's main functionalities?

Running linters on staged files

This configuration in package.json will run ESLint on staged JavaScript files and Stylelint on staged CSS files, automatically fixing any fixable issues.

"lint-staged": {
  "*.js": "eslint --fix",
  "*.css": "stylelint --fix"
}

Running custom scripts

This configuration will run markdownlint-cli2 on staged Markdown files to ensure they meet the project's markdown style requirements.

"lint-staged": {
  "*.md": "npx markdownlint-cli2"
}

Using with pre-commit hooks

This configuration sets up Husky to run lint-staged as a pre-commit hook, ensuring that the linters are run automatically before each commit.

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  }
}

Other packages similar to lint-staged

pretty-quick

pretty-quick is an npm package that runs Prettier on your changed files. It is similar to lint-staged but is specifically focused on formatting with Prettier rather than running arbitrary linters or tasks.

husky

Husky can be used to manage Git hooks and can run tasks on commit, push, and more. While it doesn't run linters on staged files by itself, it is often used in conjunction with lint-staged to trigger linters before a commit.

lefthook

Lefthook is a fast and powerful Git hooks manager for Node.js, Ruby, or any other type of projects. It can run linters and custom scripts similar to lint-staged, but it also provides additional features like parallel task execution and support for multiple programming languages.

README

lint-staged

Run linters against staged git files and don't let :poop: slip into your code base!

Why

Read the Medium post

Linting makes more sense when running before commiting you code. By doing that you can ensure no errors are going into repository and enforce code style. But running a lint process on a whole project is slow and linting results can be irrelevant. Ultimately you want to lint only files that will be committed.

This project contains a script that will run arbitary npm tasks against staged files, filtered by a spicified glob pattern.

Installation & Setup

1. npm install --save-dev lint-staged
2. Install and setup your linters just like you would do normally. Add appropriate .eslintrc and .stylelintrc etc. configs (see ESLint and Stylelint docs if you need help here).
3. Add "lint-staged": { "*.js": "eslint" } to package.json (see configuration)
4. Add { "lint-staged": "lint-staged" } to scripts section of package.json

Now git add a few files and npm run lint-staged to lint them.

I recommend using an awesome pre-commit to run lint-staged as pre-commit hook:

1. npm install --save-dev pre-commit
2. Add "pre-commit": "lint-staged" to package.json

See complete examples below.

Configuration

You can configure lint-staged by adding a lint-staged section to your package.json. It should be an object where each value is a command to run and key is a glob pattern to use for this
command. This package uses minimatch for glob patterns. See its documentation if you have questions regarding glob patterns.

{
  "scripts": {
    "my-task": "your-command",
  },
  "lint-staged": {
    "*": "my-task"
  }
}

This config will execute npm run my-task with the list of currently staged files passed as argument.

So, considering you did git add file1.ext file2.ext, lint-staged will run following command:

npm run my-task — file1.ext file2.ext

Supported are both local npm scripts (npm run-script), or any executables installed locally or globally via npm as well as any executable from your $PATH.

Using globally installed scripts is discouraged, since in this case lint-staged might not work for someone who doesn’t have it installed.

lint-staged is using npm-which to locate locally installed scripts, so you don't need to add { "eslint": "eslint" } to the scripts section of your pacakge.json. So, for simplicity, you can write:

{
  "scripts": {
    ...
  },
  "lint-staged": {
    "*.js": "eslint —fix"
  }
}

You can pass arguments to your linter separated by space. See examples below.

Starting from v2.0.0 sequences of commands are supported. Pass an array of commands instead of a single one and they will run sequentially. This is useful for running auto-formatting tools like eslint --fix or stylefmt but can be used for any arbitrary sequences.

In case of eslint --fix, after the code is reformatted we want it to be added to the same commit. This can be easily done using following config:

{
  "scripts": {
	  ...
  },
  "lint-staged": {
    "*.js": ["eslint --fix", "git add"]
  },
}

Examples

ESLint with default parameters for *.js and *.jsx running as a pre-commit hook

{
  "name": "My project",
  "version": "0.1.0",
  "scripts": {
    "lint-staged": "lint-staged"
  },
  "lint-staged": {
    "*.@(js|jsx)": "eslint"
  },
  "pre-commit": "lint-staged"
}

Automatically fix code style with --fix and add to commit

{
  "name": "My project",
  "version": "0.1.0",
  "scripts": {
    "lint-staged": "lint-staged",
  },
  "lint-staged": {
    "*.js": ["eslint --fix", "git add"]
  },
  "pre-commit": "lint-staged"
}

This will run eslint --fix and automatically add changes to the commit. Please note, that it doesn’t work well with committing hunks (git add -p).

Stylelint for CSS with defaults and for SCSS with SCSS syntax

{
  "name": "My project",
  "version": "0.1.0",
  "scripts": {
    "lint-staged": "lint-staged",
  },
  "lint-staged": {
    "*.css": "stylelint",
    "*.scss": "stylelint --syntax=scss"
  },
  "pre-commit": "lint-staged"
}

Run PostCSS sorting, add files to commit and run Stylelint to check

{
  "name": "My project",
  "version": "0.1.0",
  "scripts": {
    "lint-staged": "lint-staged"
  },
  "lint-staged": {
    "*.scss": [
      "postcss --config "[path to your config]" --replace"
      "git add",
      "stylelint"
    ]
  },
  "pre-commit": "lint-staged"
}

Changelog

v3.0.1 - 08 Sep 2016

• Switched to listr. Simplified code and more beautiful output.
• Switched to execa. Should fix #30
• Use ES2015. Dropped support for Node < 4.x
• Support commands with arguments in the lint-staged config. Closes #47
• Support binaries from $PATH. Closes #47
• Removed --color option from runner. You should pass arguments yourself.