lint-staged

library16.4.0jsnpmunverified

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.

testing devops

npm install lint-staged

github ↗package ↗

INSTALL

IMPORT

SIG · LINT-STAGED

lint-staged

testingjavascriptv16.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import lintStaged from 'lint-staged'

✗ const lintStaged = require('lint-staged')

ESM-only since v14; CommonJS require() throws. Use dynamic import for CommonJS projects.

supportsLintStaged

✓ import { supportsLintStaged } from 'lint-staged'

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

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

✓ import { runAll } from 'lint-staged'

✗ const { runAll } = require('lint-staged')

Programmatic API to run lint-staged. ESM-only. Accepts options object.

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"

lint-staged --version

Debug

Known issues

breakingESM-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.

affects: >=14.0.0

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

fix

Upgrade Node.js to v20.17 or later.

affects: >=16.4.0

deprecatedexeca 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.

affects: >=16.3.0

gotchaConfiguration 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').

affects: all

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.

affects: >=16.2.0 <16.2.7

Errors

Common errors & fixes

TypeError: lintStaged is not a function

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

fix

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

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

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.

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

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

fix

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

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

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

Upgrade

Version history

16.4.0latest on npm

Audit

Dependencies

commanderrequiredCommand-line argument parsing

execarequiredRunning shell commands (deprecated in favor of tinyexec since v16.3.0, but still used in older versions)

picomatchrequiredGlob pattern matching for file filtering (replaced micromatch in v16.4.0)

yamloptionalParsing YAML configuration files

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/lint-staged/lint-staged ↗

packagehttps://www.npmjs.com/package/lint-staged ↗