lint-staged

0.0.0-development verified Fri May 01 auth: no javascript

A tool to run linters (like ESLint, Prettier, Stylelint) against only staged git files, preventing bad code from entering the repository. Version 16 is the latest stable release, with frequent patch releases (e.g., v16.3.4). Key differentiators: it filters linters to just staged files, improving performance and relevance compared to running linters on the entire project. It supports advanced configurations like per-file-type tasks, concurrency, and automatic stash restoration. Requires a Git repository and a pre-commit hook setup (commonly via Husky).

Common errors

error Error: Cannot find module 'lint-staged' ↓

cause lint-staged is not installed or not in the PATH when running via npx/husky.

fix

Install as dev dependency: npm install --save-dev lint-staged

error ERR_REQUIRE_ESM: require() of ES Module /path/to/lint-staged/index.js from /path/to/your-script.js not supported. ↓

cause Using require() to import lint-staged in a CommonJS environment (Node <14 or without type:module).

fix

Use npx lint-staged from command line or wrap it in an ES module (e.g., use .mjs extension or set type:module in package.json).

error ✖ lint-staged failed due to a git error: error: Your local changes to the following files would be overwritten by checkout ↓

cause The stash operation conflicts with uncommitted changes that are not staged.

fix

Commit or stash all local changes before running lint-staged, or use --no-stash to disable automatic stashing.

error No staged files found for the configured patterns. ↓

cause The glob patterns in the configuration do not match any of the currently staged files.

fix

Check the list of staged files (git diff --name-only --cached) and adjust the patterns in lint-staged configuration to match them.

Warnings

breaking Since v12, lint-staged is ESM-only. Node versions <12.20.0, <14.13.1, or <16.0.0 are not supported. ↓

fix Upgrade Node.js to >=14.13.1 or >=16.0.0, and ensure your project uses ESM (i.e., type: module in package.json or .mjs extensions).

deprecated The `git add` command should not be included in tasks since v10. lint-staged automatically adds modifications from successful tasks to the index. ↓

fix Remove `git add` from task definitions. For example, change `"*.js": "eslint --fix && git add"` to `"*.js": "eslint --fix"`.

gotcha If a task fails, the original staged state is automatically restored. However, if staging fails (e.g., due to files being modified after the initial stash), the stash may not be restored correctly, leaving the working directory in an intermediate state. ↓

fix Use `--no-stash` to disable automatic stash if you do not want lint-staged to restore changes on failure, but be aware that modified files from successful tasks will remain.

breaking Node.js 12 support dropped in v13.0.0. Version 12 is also ESM-only from v12.0.0. ↓

fix Upgrade Node.js to >=14.13.1 or >=16.0.0.

gotcha When using `--concurrent` option, tasks are run in parallel. This can cause conflicts if tasks modify the same files. ↓

fix Use `--concurrent false` to run tasks sequentially, or design tasks to work on different file types.

Install

npm install canary-farm-lint-staged

yarn add canary-farm-lint-staged

pnpm add canary-farm-lint-staged

Imports

lint-staged
wrong
```
const lintStaged = require('lint-staged')
```
correct
```
npx lint-staged --config .lintstagedrc.json
```
lint-staged is typically used as a CLI tool, not a library import. Since v12, the package is ESM-only and requires Node >=14.13.1 or >=16. Using require() will fail with ERR_REQUIRE_ESM.
export default
wrong
```
import lintStaged from 'lint-staged'
```
correct
```
// No programmatic API; use CLI or define in package.json
"lint-staged": {
  "*.js": "eslint --fix"
}
```
There is no programmatic API; lint-staged is designed to be run as a CLI tool or via git hooks. Attempting to import the package directly will result in runtime errors.
Configuration
wrong
```
{
  "*.js": "eslint --fix && git add"
}
```
correct
```
// In .lintstagedrc.json:
{
  "*.js": ["eslint --fix", "git add"]
}
```
Since v10, lint-staged automatically adds any modifications to the index, so the `git add` step should not be included in the task. Including it may cause duplicate additions or conflicts.

Quickstart

Complete setup of lint-staged with Husky, including installation, hook setup, and configuration example for ESLint and Prettier.

// 1. Install
npm install --save-dev lint-staged husky

// 2. Set up husky pre-commit hook
npx husky add .husky/pre-commit "npx lint-staged"

// 3. Add configuration to package.json:
"lint-staged": {
  "*.js": "eslint --fix",
  "*.{css,md}": "prettier --write"
}

// 4. Make a change and commit:
git add some-file.js
git commit -m "Add something"
// This will run eslint and prettier on the staged files before commit.