The Practical Developer

Pre-Commit Hooks That Pay For Themselves: Husky, lint-staged, And The Five Rules That Stick

March 17, 2023 by The Practical Developer

Most teams install Husky, configure ten pre-commit checks, and disable the whole thing within a month because commits take 30 seconds. Here is the minimal pre-commit setup that catches real bugs, runs in under 2 seconds on the changed files only, and does not need a `--no-verify` workaround.

productivity

devops

tools

Hands at a keyboard — the moment before a commit is the right place to catch a typo

A team installs Husky on Tuesday. Wednesday they add ESLint, Prettier, TypeScript check, and a unit-test pass to the pre-commit hook. By Friday, every commit takes 30 seconds. By the following Tuesday, three engineers are using --no-verify for every commit and the hooks are disabled.

This is the pre-commit hook anti-pattern: piling everything into the hook until the hook is unusable, then bypassing it. The fix is to move 90% of the checks to CI where they belong, and to keep pre-commit narrow, fast, and operating only on the files actually staged. Done right, the hook catches the dumb mistakes before they get committed and runs in under two seconds.

The rules that make hooks survive

Five rules, in priority order. If you violate one, the hook gets bypassed.

1. Run only on staged files. A pre-commit hook that lints the entire repo on every commit is a punishment, not a tool. Use lint-staged to filter to the files actually being committed.

2. Check, do not run. The hook should verify the change is committable, not run the full test suite. Linting, formatting, type-checking on the diff — yes. End-to-end tests — no. Save those for CI.

3. Auto-fix when safe. Prettier, lint —fix, import sorting — these are deterministic and never wrong. Apply them to staged files and re-stage automatically. The developer never sees them.

4. Two-second budget. A pre-commit hook should run in under two seconds for a typical commit. Anything more and developers reach for --no-verify. If you cannot stay under two seconds, you are doing the wrong thing in the hook.

5. Have an escape hatch. Sometimes you need to commit broken code intentionally (work-in-progress, fixing a previous commit). git commit --no-verify exists for a reason; do not punish people for using it. CI is the gate that matters.

A minimal setup that works

npm i -D husky lint-staged
npx husky init

.husky/pre-commit:

#!/usr/bin/env bash
npx lint-staged

package.json:

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ],
    "*.css": [
      "prettier --write"
    ]
  }
}

That is the entire setup. lint-staged runs only against files matching the glob, only the ones staged for commit. Auto-fixes are applied and re-staged. A typical commit touches 1–5 files; the hook runs in 0.5–1.5 seconds.

What I add: a TypeScript surface check

ESLint catches per-file errors. It does not catch type errors that span files (because each file is checked in isolation). For TypeScript projects, I add a fast type-check that uses tsc in incremental mode:

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "bash -c 'tsc --noEmit --incremental'"
    ]
  }
}

--incremental writes a .tsbuildinfo cache. The first run is slow; subsequent runs check only what has changed. About 2 seconds on a mid-size codebase.

If your TypeScript project is large and tsc --noEmit is slow even incrementally, drop it from pre-commit and rely on CI. The two-second rule is non-negotiable.

What NOT to put in pre-commit

A list of common mistakes:

  • Full test suite. Even a “fast” test suite is rarely under 2 seconds. Run it in CI. Use git push hooks for staged-and-uncommitted-related tests if you want, but pre-commit is too aggressive.
  • tsc without --incremental on a large project. 30 seconds. Use CI.
  • Build the project. Builds belong in CI.
  • Run a Docker container. Disk and startup overhead violate the two-second budget.
  • Commit message linting in the pre-commit hook. That is what commit-msg is for. Keep them separate so they fail loudly.

Useful supplements

A few hooks I add on top of the default:

Block accidental secret commits. Use secretlint or a custom regex to refuse commits that look like they contain credentials.

{
  "lint-staged": {
    "*": "secretlint"
  }
}

Block large files. Stops the well-meaning developer from accidentally committing a 50MB binary.

# .husky/pre-commit
git diff --cached --name-only --diff-filter=ACM | xargs -I {} bash -c '
  size=$(wc -c < "$1");
  if [ "$size" -gt 1048576 ]; then
    echo "ERROR: $1 is $(($size/1024))KB. Refusing to commit files >1MB. Use Git LFS." >&2
    exit 1
  fi
' bash {}

Format package.json deterministically. Different yarn/npm versions order keys differently; standardize:

{
  "lint-staged": {
    "package.json": "sort-package-json"
  }
}

Block console.log in non-test files. Optional and opinionated — but useful if your team has a “no console.log in production code” policy.

{
  "lint-staged": {
    "src/**/*.{ts,tsx}": ["eslint --rule 'no-console: error' --no-eslintrc"]
  }
}

commit-msg: the conventional-commits gate

If your team uses conventional commits (feat:, fix:, chore:), enforce the format with a commit-msg hook. This catches typos before they land in the history.

npm i -D @commitlint/cli @commitlint/config-conventional
echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js

.husky/commit-msg:

#!/usr/bin/env bash
npx --no -- commitlint --edit "${1}"

Now git commit -m "wip" fails with a clear error pointing to the rule. Reject force is the right behavior here — bad commit messages stay in history.

pre-push: the bigger nets

Some checks are too expensive for pre-commit but too important to skip until PR. The pre-push hook is the right place: runs on push, not on every commit.

# .husky/pre-push
#!/usr/bin/env bash
npm run typecheck
npm run test:unit

A 30-second pre-push that catches “your branch does not even compile” before it hits CI is much less painful than a 30-second pre-commit, because most engineers push only a few times per day.

The CI side: do everything pre-commit doesn’t

Pre-commit is the spell-check; CI is the editor. CI runs:

  • Full ESLint (not just on staged files)
  • Full TypeScript check
  • All tests
  • Bundle-size check
  • Visual regression
  • Integration / E2E tests
  • Security scans

If a CI check is fast and catches a class of bugs nobody else can catch, consider moving it to pre-push. Anything else stays in CI.

When the hook is a problem

Three signs that the hook is hurting more than helping:

  • Engineers use --no-verify regularly. The hook is slow or wrong. Fix it or remove it.
  • The hook fails on commits that CI then passes. The hook is checking something CI is not, or vice versa. Align them.
  • Onboarding a new engineer takes a half-hour to set up Husky. The setup is too fragile. Use husky install configured to run automatically on npm install ("prepare": "husky" in package.json).

A prepare script that just works

The most painless way to install hooks for new contributors:

{
  "scripts": {
    "prepare": "husky"
  }
}

npm install triggers prepare automatically. The hooks are set up the moment a developer clones and installs. No README step, no manual run.

The takeaway

A pre-commit hook is a 2-second sanity check, not a CI replacement. lint-staged + ESLint —fix + Prettier —write covers 90% of what is useful. Anything that takes longer than two seconds belongs in pre-push or CI. Auto-fix when safe, escape hatch when not. The team that gets this right barely notices the hook is there — and saves a small amount of CI time per PR because the dumb mistakes never make it that far.

The hook that survives is invisible. The hook that everyone bypasses is worse than no hook. Aim for invisible.

A note from Yojji

The kind of developer-experience polish that makes “the hooks are fast and useful” feel obvious instead of a quarterly debate — the small workflow rituals that compound over hundreds of commits — is the kind of detail Yojji’s teams put into the codebases they hand back to clients.

Yojji is an international custom software development company founded in 2016, with teams across Europe, the US, and the UK. They specialize in the JavaScript ecosystem (React, Node.js, TypeScript), cloud platforms (AWS, Azure, GCP), and full-cycle product engineering — including the developer-experience tooling that decides whether a codebase feels good to work in.