lefthook Configuration

lefthook is a fast and powerful Git hooks manager that replaces tools like Husky. The template uses lefthook to run code quality checks automatically before commits.

Configuration File (`lefthook.yml`)

The main configuration file for lefthook is located at the project root:

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.js"
        - "**/*.jsx"
        - "**/*.ts"
        - "**/*.tsx"
        - "**/*.json"
        - "**/*.jsonc"
        - "**/*.css"
      stage_fixed: true

Configuration Explained

Pre-commit Hook

The template configures a pre-commit hook that runs before each commit:

pre-commit:
  jobs:
    - run: npx ultracite fix

pre-commit: The Git hook that runs before git commit
jobs: List of jobs to execute
run: The command to execute

Command

run: npx ultracite fix

This command:

Uses npx to run the locally installed ultracite
Executes the fix command, which runs Biome to automatically fix linting and formatting issues

The template uses ultracite as a wrapper around Biome, providing a unified interface for code quality checks.

File Patterns

The glob section specifies which files the hook should process:

glob:
  - "**/*.js"
  - "**/*.jsx"
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.json"
  - "**/*.jsonc"
  - "**/*.css"

This includes:

JavaScript files (.js, .jsx)
TypeScript files (.ts, .tsx)
JSON files (.json, .jsonc)
CSS files (.css)

The **/* pattern matches files in all directories recursively.

Stage Fixed Files

stage_fixed: true

This option:

Automatically stages files that were modified by the hook
Ensures that formatting and linting fixes are included in the commit
Prevents the need to manually stage fixed files

How lefthook Works

Installation

lefthook is automatically installed as a dev dependency:

{
  "devDependencies": {
    "lefthook": "^2.1.9"
  }
}

When you run pnpm install, lefthook automatically sets up the Git hooks in the .git/hooks directory.

Hook Execution Flow

Before Commit: When you run git commit, Git triggers the pre-commit hook
lefthook Execution: lefthook runs the configured jobs
Code Quality Check: ultracite (Biome) checks and fixes all staged files matching the glob patterns
File Staging: Any files modified by the fixes are automatically staged
Commit Completion: If all checks pass, the commit is completed

Error Handling

If the hook fails:

The commit is aborted
You'll see error messages indicating what went wrong
Fix the issues and try committing again

Using lefthook

Manual Hook Execution

You can manually run the pre-commit hook:

# Run the pre-commit hook manually
pnpm exec lefthook run pre-commit

# Run all hooks
pnpm exec lefthook run

Skip Hooks

To skip hooks for a specific commit:

# Skip pre-commit hooks
git commit --no-verify -m "Your commit message"

# Skip all hooks
git commit --no-verify --no-pre-commit -m "Your commit message"

Skipping hooks should be done sparingly, as it bypasses important quality checks.

Check Hook Status

Check which hooks are configured and their status:

pnpm exec lefthook status

List Available Hooks

List all configured hooks:

pnpm exec lefthook list

Customizing lefthook Configuration

Add Multiple Jobs

Add multiple jobs to run in sequence:

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.ts"
        - "**/*.tsx"
    - run: pnpm run test
      glob:
        - "**/*.test.ts"

Add Different Hook Types

Add hooks for different Git events:

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.ts"

pre-push:
  jobs:
    - run: pnpm run test

post-merge:
  jobs:
    - run: pnpm install

Customize File Patterns

Customize which files are processed:

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "src/**/*.ts"
        - "test/**/*.ts"
        - "*.config.ts"

Add Custom Commands

Add custom commands to run:

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.ts"
    - run: echo "Running custom check..."
      glob:
        - "**/*.ts"

Configure Parallel Execution

Run jobs in parallel:

pre-commit:
  parallel: true
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.ts"
    - run: pnpm run lint
      glob:
        - "**/*.ts"

Add Environment Variables

Set environment variables for hook execution:

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.ts"
      env:
        - "NODE_ENV=development"
        - "DEBUG=true"

Common Use Cases

Run Tests Before Commit

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.ts"
    - run: pnpm run test

Run Build Before Push

pre-push:
  jobs:
    - run: pnpm run build

Check Dependencies After Merge

post-merge:
  jobs:
    - run: pnpm install

Custom Quality Checks

pre-commit:
  jobs:
    - run: npx ultracite fix
      glob:
        - "**/*.ts"
    - run: npx tsc --noEmit
      glob:
        - "**/*.ts"

Troubleshooting

Hooks Not Running

If hooks are not running:

Check if lefthook is installed:
```
pnpm list lefthook
```
Check if hooks are configured:
```
pnpm exec lefthook list
```
Check if Git hooks are installed:
```
ls -la .git/hooks/
```
Reinstall hooks:
```
pnpm exec lefthook install
```

Hooks Failing

If hooks are failing:

Run the hook manually to see the error:
```
pnpm exec lefthook run pre-commit
```
Check the error message and fix the issues
Ensure all required dependencies are installed

Permission Issues

If you get permission errors:

Remove the hooks directory:
```
rm -rf .git/hooks/
```
Reinstall hooks:
```
pnpm exec lefthook install
```

Slow Hook Execution

If hooks are running slowly:

Limit the file patterns to only necessary files
Consider running heavy checks (like tests) in pre-push instead of pre-commit
Use stage_fixed: true to avoid re-running on fixed files

Migration from Husky

If you're migrating from Husky to lefthook:

Remove Husky:
```
pnpm remove husky
rm -rf .husky/
```
Install lefthook:
```
pnpm add -D lefthook
```
Create lefthook.yml with your hook configurations
lefthook will automatically set up the Git hooks

TPT