lint-staged

Lint files staged by git

weekly downloads16.5M

versionv16.2.7

licenseMIT

categorytoolchain

lintgitstagedeslintprettierstylelintcodequalitycheckformatvalidate

Overview

lint-staged is a Node.js tool that executes linters, formatters, and validation scripts exclusively on files staged in Git for commit. Instead of running ESLint or Prettier against your entire codebase (which can take minutes in large projects), it targets only the files you've staged with git add. This dramatically reduces pre-commit hook execution time and makes code quality enforcement practical even in monorepos with thousands of files.

The package works by intercepting Git's list of staged files, matching them against glob patterns you define, and running corresponding commands. When a tool like Prettier auto-fixes formatting issues, lint-staged automatically re-stages the modified files so your commit includes the corrections. It integrates seamlessly with Git hook managers like Husky, typically running in a pre-commit hook to block commits that fail linting rules.

With over 16 million weekly downloads, lint-staged has become the de facto standard for JavaScript teams enforcing code quality at commit time. It's used across open-source projects and enterprise codebases to ensure consistent formatting, catch errors before CI, and maintain standards without slowing down developer workflows. The tool supports any command-line utility—ESLint, Prettier, Stylelint, TypeScript compiler checks, custom scripts—making it flexible for diverse toolchains.

Developers adopt lint-staged to shift quality checks left in the development cycle. Rather than discovering linting errors in CI pipelines (which delay feedback), issues surface immediately during commit. This fail-fast approach reduces context switching and keeps main branches clean, while the staged-file scoping ensures the process remains fast enough that developers won't bypass hooks.

Quick Start

typescript

// package.json configuration
{
  "devDependencies": {
    "lint-staged": "^16.2.7",
    "husky": "^9.0.0",
    "eslint": "^8.57.0",
    "prettier": "^3.2.5"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,css}": "prettier --write",
    "*.ts": "tsc --noEmit --skipLibCheck"
  }
}

// .husky/pre-commit (after running: npx husky init)
#!/usr/bin/env sh
npx lint-staged

// Alternative: standalone .lintstagedrc.json
{
  "*.{js,ts}": "eslint --cache --fix",
  "*.{js,ts,css,md}": "prettier --write",
  "package.json": "sort-package-json"
}

// Example function-based config for complex logic (.lintstagedrc.js)
module.exports = {
  '*.js': (filenames) => [
    `eslint --fix ${filenames.join(' ')}`,
    `jest --bail --findRelatedTests ${filenames.join(' ')}`,
  ],
  '*.ts': (filenames) => {
    const files = filenames.join(' ');
    return [
      `prettier --write ${files}`,
      `eslint --fix ${files}`,
      'tsc --noEmit',
    ];
  },
};

Use Cases

Pre-commit linting enforcement: Automatically run ESLint with --fix on staged JavaScript and TypeScript files before every commit. If linting fails, the commit is blocked until errors are resolved. Auto-fixed issues get re-staged and included in the commit, ensuring your repository never contains unfixed lint violations.

Consistent code formatting: Execute Prettier on staged files to enforce formatting standards across teams. Developers don't need to remember to format—lint-staged handles it transparently during commit. Works for JavaScript, TypeScript, JSON, Markdown, CSS, and any format Prettier supports.

Monorepo optimization: In large monorepos with multiple packages, running full-project linting can exceed 30 seconds. lint-staged reduces this to under 2 seconds by processing only changed files, making pre-commit hooks practical even with hundreds of thousands of lines of code.

TypeScript type checking on changed files: Run tsc --noEmit selectively on staged .ts files to catch type errors before commit. Combined with build caching, this provides fast type safety feedback without full project compilation.

Custom validation scripts: Execute project-specific checks like license header validation, import sorting (via eslint-plugin-import), or detecting secrets (using tools like detect-secrets). Any shell command or Node.js script can run against matched file patterns, enabling custom quality gates tailored to your project's needs.

Pros & Cons

Pros

+Dramatically faster than full-project linting—only processes staged files, reducing pre-commit times from minutes to seconds in large codebases
+Automatically re-stages files modified by auto-fix tools (Prettier, ESLint --fix), ensuring corrections are included in commits without manual intervention
+Flexible configuration via glob patterns supports any linter, formatter, or shell command, enabling custom workflows beyond standard JavaScript tooling
+Prevents broken code from entering version control by blocking commits that fail checks, catching issues before CI and reducing pipeline failures
+Works seamlessly with Husky and other Git hook managers, with straightforward JSON or YAML configuration requiring minimal setup

Cons

−Cannot catch issues in unchanged files—if a refactor breaks untouched code, lint-staged won't detect it since those files aren't staged
−Requires Git-based workflow—won't function in non-Git environments or with alternative version control systems
−Can create confusing scenarios when auto-fixes fail mid-process; if a command modifies files then errors, partially applied changes may leave the working directory in an inconsistent state
−Adds commit latency—even optimized, pre-commit hooks introduce 1-5 second delays that some developers find disruptive to flow
−Configuration complexity grows with project size; managing multiple glob patterns and command sequences for different file types can become unwieldy in large monorepos

Alternatives

huskyv9.1.7

Modern native Git hooks

toolchaingithooks

20.9M / week

Comparisons

husky vs lint-staged

toolchain

Install

bash

npm install lint-staged

bash

pnpm add lint-staged

bash

bun add lint-staged

Overview

Quick Start

typescript

// package.json configuration
{
  "devDependencies": {
    "lint-staged": "^16.2.7",
    "husky": "^9.0.0",
    "eslint": "^8.57.0",
    "prettier": "^3.2.5"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,css}": "prettier --write",
    "*.ts": "tsc --noEmit --skipLibCheck"
  }
}

// .husky/pre-commit (after running: npx husky init)
#!/usr/bin/env sh
npx lint-staged

// Alternative: standalone .lintstagedrc.json
{
  "*.{js,ts}": "eslint --cache --fix",
  "*.{js,ts,css,md}": "prettier --write",
  "package.json": "sort-package-json"
}

// Example function-based config for complex logic (.lintstagedrc.js)
module.exports = {
  '*.js': (filenames) => [
    `eslint --fix ${filenames.join(' ')}`,
    `jest --bail --findRelatedTests ${filenames.join(' ')}`,
  ],
  '*.ts': (filenames) => {
    const files = filenames.join(' ');
    return [
      `prettier --write ${files}`,
      `eslint --fix ${files}`,
      'tsc --noEmit',
    ];
  },
};

Use Cases

Pros & Cons

Pros

+Dramatically faster than full-project linting—only processes staged files, reducing pre-commit times from minutes to seconds in large codebases
+Automatically re-stages files modified by auto-fix tools (Prettier, ESLint --fix), ensuring corrections are included in commits without manual intervention
+Flexible configuration via glob patterns supports any linter, formatter, or shell command, enabling custom workflows beyond standard JavaScript tooling
+Prevents broken code from entering version control by blocking commits that fail checks, catching issues before CI and reducing pipeline failures
+Works seamlessly with Husky and other Git hook managers, with straightforward JSON or YAML configuration requiring minimal setup

Cons

−Cannot catch issues in unchanged files—if a refactor breaks untouched code, lint-staged won't detect it since those files aren't staged
−Requires Git-based workflow—won't function in non-Git environments or with alternative version control systems
−Can create confusing scenarios when auto-fixes fail mid-process; if a command modifies files then errors, partially applied changes may leave the working directory in an inconsistent state
−Adds commit latency—even optimized, pre-commit hooks introduce 1-5 second delays that some developers find disruptive to flow
−Configuration complexity grows with project size; managing multiple glob patterns and command sequences for different file types can become unwieldy in large monorepos