Husky & lint-staged (Pre-commit Hooks)

Run ESLint and Prettier automatically on staged files before each commit to catch issues early.

Recipe

Quick-reference recipe card - copy-paste ready.

# Install husky and lint-staged
npm install --save-dev husky lint-staged
 
# Initialize husky
npx husky init
 
# The init command creates .husky/pre-commit
# Edit it to run lint-staged
echo "npx lint-staged" > .husky/pre-commit

When to reach for this: Any team project where you want to guarantee that committed code passes linting and formatting checks.

Working Example

# .husky/pre-commit
npx lint-staged

// package.json
{
  "scripts": {
    "lint": "next lint",
    "format": "prettier --write .",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix --no-warn-ignored",
      "prettier --write"
    ],
    "*.{css,json,md}": [
      "prettier --write"
    ]
  }
}

What this demonstrates:

• Husky hooks into Git's pre-commit event
• lint-staged runs ESLint and Prettier only on files that are staged (git add)
• TypeScript files get both linted and formatted; other files get formatted only
• The prepare script ensures husky installs automatically after npm install

Deep Dive

How It Works

• Husky uses Git hooks (.husky/pre-commit) to run commands before each commit
• lint-staged collects files from git diff --staged and passes them to the configured commands
• Commands run in sequence per glob pattern - if ESLint fails, Prettier does not run, and the commit is blocked
• Fixed files are automatically re-staged so the commit includes the fixes
• The prepare script runs after npm install, ensuring hooks are set up for every developer

Variations

With Biome instead of ESLint + Prettier:

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx,json,css}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

With type-checking (slower but thorough):

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix --no-warn-ignored",
      "prettier --write"
    ]
  }
}

# .husky/pre-commit
npx lint-staged
npx tsc --noEmit

Note: tsc --noEmit checks the entire project, not just staged files, because TypeScript needs full project context.

Commit message linting with commitlint:

npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "npx commitlint --edit \$1" > .husky/commit-msg

// commitlint.config.js
export default { extends: ["@commitlint/config-conventional"] };

Skipping hooks (escape hatch):

# When you really need to bypass (debugging, WIP commits)
git commit --no-verify -m "WIP: work in progress"

TypeScript Notes

// lint-staged passes file paths to ESLint, which works with
// TypeScript files seamlessly as long as @typescript-eslint
// is configured.
 
// Note: ESLint --fix can auto-fix some TypeScript issues:
// - Remove unused imports
// - Add `type` keyword to type-only imports
// - Fix consistent-type-imports violations

Gotchas

Things that will bite you. Each gotcha includes what goes wrong, why it happens, and the fix.

• Hooks not running after clone - Git hooks are not committed to the repo; they live in .git/hooks/. New developers need to run npm install (which triggers prepare). Fix: Ensure "prepare": "husky" is in your package.json scripts.

• ESLint warnings on ignored files - When lint-staged passes file paths to ESLint, files matching your ESLint ignores trigger warnings. Fix: Add --no-warn-ignored flag to the ESLint command in lint-staged config.

• Partial staging issues - If you stage only part of a file (git add -p), lint-staged operates on the full file, which may include unstaged changes. Fix: Be aware of this limitation. For critical cases, commit the full file.

• Slow pre-commit hooks - Running type-checking (tsc) on every commit can take 10 or more seconds on large projects. Fix: Run tsc only in CI. Keep pre-commit hooks fast by limiting them to ESLint and Prettier on staged files.

• CI does not run hooks - Git hooks are local only. CI environments do not execute pre-commit hooks. Fix: Always run lint and format checks in CI as a safety net. See Linting in CI/CD.

Alternatives

Other ways to solve the same problem - and when each is the better choice.

FAQs

git commit --no-verify -m "WIP: work in progress"

# .husky/pre-commit
npx lint-staged
npx tsc --noEmit

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx,json,css}": [
      "biome check --write --no-errors-on-unmatched"
    ]
  }
}

npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "npx commitlint --edit \$1" > .husky/commit-msg

Related

• ESLint Setup for Next.js - ESLint configuration for the lint step
• Prettier Setup - Prettier configuration for the format step
• ESLint + Prettier Integration - ensure no conflicts between the two
• Linting in CI/CD - CI safety net for hooks
• EditorConfig & VS Code Settings - editor-level consistency