Husky Configuration

What is Husky?

Husky is a Git hooks manager that automates tasks before commits, pushes, or other Git actions. It helps ensure code quality by running linters, formatters, tests, and other checks before changes enter your repository.

TL;DR

Use Husky to run git hooks (pre-commit, pre-push, commit-msg). Combine Husky with `lint-staged` for fast, staged-file checks. Add a `prepare` script so hooks install automatically for contributors.

Why Use Husky?

Use Husky to prevent broken code from being committed, to enforce team standards, and to catch issues early in the development workflow.

Example: checks before commit

1# Before commit, Husky automatically runs:
2# ✓ ESLint checks (no errors allowed)
3# ✓ Prettier formatting (code must be formatted)
4# ✓ Unit tests (all must pass)
5# ✓ Type checking (no TypeScript errors)
6
7# If any check fails → Commit is blocked ❌
8# If all checks pass → Commit proceeds ✅

Installation

Prerequisite: your project must be a Git repository.

1# Install Husky
2npm install --save-dev husky
3
4# Initialize Husky (creates .husky/ and a sample hook)
5npx husky init

Basic Setup

Create a pre-commit hook

Create or edit the `.husky/pre-commit` hook to run linting and formatting:

1#!/usr/bin/env sh
2. "$(dirname -- "$0")/_/husky.sh"
3
4npm run lint
5npm run format
6npm test

Using lint-staged (recommended)

For fast commits run only on staged files, call `npx lint-staged` from your pre-commit hook. This keeps hooks quick and focused.

1# Install both tools
2npm install --save-dev husky lint-staged
3
4# Initialize Husky
5npx husky init
6
7# Create pre-commit hook
8npx husky add .husky/pre-commit "npx lint-staged"

Common Hooks

pre-commit

Run linters, formatters, and quick tests before creating a commit.

1#!/usr/bin/env sh
2. "$(dirname -- "$0")/_/husky.sh"
3
4npx lint-staged

commit-msg

Validate commit messages (e.g. with commitlint) before accepting the commit.

1#!/usr/bin/env sh
2. "$(dirname -- "$0")/_/husky.sh"
3
4npx --no -- commitlint --edit $1

pre-push

Run tests and builds before pushing to remote.

1#!/usr/bin/env sh
2. "$(dirname -- "$0")/_/husky.sh"
3
4npm run test
5npm run build

Package.json Scripts

Add a `prepare` script so Husky is installed for contributors:

1{
2  "scripts": {
3    "prepare": "husky install"
4  }
5}

Commit Message Validation

Install commitlint to enforce commit message conventions (Conventional Commits):

1npm install --save-dev @commitlint/cli @commitlint/config-conventional

1// commitlint.config.js
2module.exports = {
3  extends: ['@commitlint/config-conventional'],
4};

Bypassing Hooks (Emergency Only)

Use these only for urgent fixes — document and follow up with a fix.

1# Skip pre-commit hook
2git commit --no-verify -m "emergency fix"
3
4# Skip pre-push
5git push --no-verify

Troubleshooting

• Run `npm run prepare` or `npx husky install` if hooks are missing.
• Ensure `.husky/*` scripts are executable on Unix: `chmod +x .husky/*`.
• On Windows, set the executable bit in Git index: `git update-index --chmod=+x .husky/pre-commit`.

Quick verification

1# Ensure hooks are installed
2    pnpm run prepare
3
4    # Test pre-commit (simulate a commit)
5    git add .
6    git commit -m "test commit" --no-verify  # skip hooks for manual test
7
8    # Run lint-staged manually
9    npx lint-staged

Ready For Production

• Add `prepare` script to `package.json` (husky install)
• Keep hooks fast: use `lint-staged` for staged-file checks
• Document any allowed bypass policies and emergency procedures

Resources

• Husky Docs
• Husky GitHub