lint-staged

16.4.0 verified Fri May 01 auth: no javascript

lint-staged is a tool that runs linters and formatters against staged git files, preventing subpar code from entering the repository. It only processes files that are staged for commit, making it faster and more relevant than running the same tools on the entire codebase. The current stable version is 16.4.0, released in early 2025. It is actively maintained with frequent patch releases. Key differentiators include support for git stash backup, rollback on failure, flexible configuration using multiple file formats, and integration with popular tools like ESLint, Prettier, and Stylelint. It replaces micromatch with picomatch in v16.4.0 for reduced dependencies. Requires Node.js >=20.17.

Common errors

error TypeError: lintStaged is not a function ↓

cause Using require('lint-staged') in CommonJS after v14 (ESM-only).

fix

Use dynamic import: const lintStaged = await import('lint-staged').

error Error: Could not find a configuration file for 'lint-staged' ↓

cause No .lintstagedrc or lint-staged config in package.json.

fix

Add a configuration file (e.g., .lintstagedrc.json) or add 'lint-staged' key to package.json.

error Warning: Task 'eslint' failed with exit code 1. Not saving stash. ↓

cause ESLint found errors or warnings that it cannot auto-fix.

fix

Fix the errors manually or add --quiet to ESLint command to ignore warnings.

error fatal: could not open '.git/index.lock': File exists. ↓

cause Another git process is running (e.g., another commit or rebase).

fix

Wait for the other process to finish or remove the lock file: rm .git/index.lock

Warnings

breaking ESM-only since v14: require() throws ERR_REQUIRE_ESM. Use dynamic import or upgrade to ESM project. ↓

fix Replace const x = require('lint-staged') with const x = await import('lint-staged') in CommonJS, or convert project to ESM.

breaking Node.js >=20.17 required since v16.4.0. Older Node versions will fail. ↓

fix Upgrade Node.js to v20.17 or later.

deprecated execa replaced by tinyexec in v16.3.0. If you rely on execa-specific behavior, update your configuration. ↓

fix Ensure tasks do not depend on execa features like shell option; use tinyexec-compatible commands.

gotcha Configuration paths are relative to the project root, not to the staged file location. Misconfigured paths cause false failures. ↓

fix Use absolute paths or paths relative to the project root (e.g., './eslint.config.js' not './src/eslint.config.js').

gotcha --continue-on-error flag may cause tasks to be killed with SIGINT if one fails, especially in v16.2.6 and earlier. ↓

fix Upgrade to v16.2.7 or later. In older versions, avoid --continue-on-error or handle SIGINT.

Install

npm install lint-staged

yarn add lint-staged

pnpm add lint-staged

Imports

default
wrong
```
const lintStaged = require('lint-staged')
```
correct
```
import lintStaged from 'lint-staged'
```
ESM-only since v14; CommonJS require() throws. Use dynamic import for CommonJS projects.

supportsLintStaged

wrong

const supportsLintStaged = require('lint-staged').supportsLintStaged

correct

import { supportsLintStaged } from 'lint-staged'

Utility function to check if lint-staged is configured in the project. ESM only.

loadConfig
```
import { loadConfig } from 'lint-staged'
```
Loads lint-staged configuration programmatically. Returns parsed config object.
runAll
wrong
```
const { runAll } = require('lint-staged')
```
correct
```
import { runAll } from 'lint-staged'
```
Programmatic API to run lint-staged. ESM-only. Accepts options object.

Quickstart

Shows basic configuration: lint-staged will run eslint --fix on staged .js files and prettier --write on staged .json/.md files. The pre-commit hook (via husky) triggers lint-staged.

// .lintstagedrc.json
{
  "*.js": "eslint --fix",
  "*.{json,md}": "prettier --write"
}

// package.json (scripts section)
{
  "scripts": {
    "precommit": "lint-staged"
  }
}

// or use husky (pre-commit hook)
// npx husky add .husky/pre-commit "npx lint-staged"