Lefthook Setup Guide
Why Lefthook?
Lefthook runs automated checks before each commit — catching bugs, formatting issues, and lint errors before they reach production. Unlike Git hooks that live in .git/hooks (not tracked by Git), Lefthook stores its configuration in lefthook.yml which gets committed to the repository, so every team member gets the same hooks automatically.
- Frontend ESLint validation
- Backend Go tests
- Backend format checks
If any check fails, the commit is rejected.
Prerequisites
- Node.js 18+
- npm
- Go 1.21+ (if running Go checks)
Verify your versions:
node -v
npm -v
go version
Install Lefthook
From your project root:
npm install --save-dev lefthook
npx lefthook install
The output will show sync hooks: pre-commit, commit-msg (or whichever hooks are configured).
Verify Installation
npx lefthook run pre-commit
This runs all checks configured for the pre-commit hook without waiting for an actual commit.
Normal Development Flow
Before committing:
git add .
git commit -m "your message"
Lefthook runs automatically. If any check fails, the commit is rejected. Fix the issue and commit again.
Troubleshooting
If Lefthook is not running on commit:
npx lefthook install
Skip hooks temporarily (emergency only):
git commit --no-verify -m "message"
Configuration
The configuration lives in lefthook.yml at the project root. Here is an example with frontend and backend checks:
pre-commit:
jobs:
backend-test:
root: backend/
run: go test ./...
frontend-lint:
root: customer/
run: npm run lint
After changing lefthook.yml, run npx lefthook install to sync the hooks.
Team Setup
All developers must install Lefthook before contributing. Commit package.json, package-lock.json, and lefthook.yml to Git. Do not commit .git/hooks. When other developers clone the repository, they run npm install and then npx lefthook install to get the same hooks.