How to use lint-staged: setup, config and common tips

Why run checks on staged files only?

Formatters and linters are most useful when they run before you commit, because that keeps errors out of the repository and enforces a consistent code style. Running them on a whole project can be slow, and opinionated tasks can produce results for files you are not changing.

lint-staged filters tasks down to the files that will be committed. The README describes it as a script that runs shell tasks with a list of staged files as an argument, filtered by a glob pattern.

Install lint-staged in your project

You need Node.js, npm and git. Install lint-staged as a dev dependency with the following command. The README notes that it requires further setup before it does anything useful.

• Run the install command in your project folder.
• Commit the changes to package.json so teammates get the same setup.

Set up a pre-commit git hook

lint-staged is meant to run on the pre-commit git hook. The README recommends Husky as a popular way to configure git hooks, and links to the git documentation on hooks if you want to learn more.

Also install the tools you want to run, such as ESLint or Prettier. lint-staged runs them; it does not replace them.

• Install and configure Husky, or another hook manager such as lefthook or simple-git-hooks.
• Make sure the pre-commit hook calls lint-staged.
• Commit the .husky folder so the setup is shared with your team.

Configure lint-staged to run your tools

Configuration maps file patterns to commands. The README gives this example, which runs ESLint on all staged JavaScript files. Each key is a glob pattern and each value is the command to run on the matching staged files.

See the configuration and filtering sections of the README for more options, including JS configuration files and running several commands in sequence.

Test it with a commit

Change a few files, stage some of them with git add (or git add --patch), and run git commit. lint-staged runs your configured tasks against the staged files and reports the result. The README example shows Prettier running on staged JSON and Markdown files.

lint-staged backs up your working state with a git stash before running tasks. The README warns that it runs git operations that affect your files, so review changes after a failed run.

• Only staged files are checked by default.
• Use npx lint-staged --help to see all command line flags.

Useful command line flags

The README lists flags for changing how lint-staged runs. Some common ones are --concurrent to control how many tasks run in parallel, --quiet to hide lint-staged's own output, --verbose to show task output even when tasks succeed, and --debug to log extra information.

The --all flag runs tasks on all files tracked in git instead of only staged ones. The README says it is useful for running on a clean state, for example in CI.

• --concurrent: set number of parallel tasks, or false for serial.
• --config: point to a specific config file, or read it from stdin with -.
• --continue-on-error: run all tasks even if one fails.
• --no-stash: turn off the automatic backup stash.