@kcconfigs/lefthook

Shared Lefthook configuration for Git hooks. Provides composable presets, features, and individual hook definitions that can be mixed and matched via Lefthook's extends mechanism.

• Prerequisites
• Installation
• Usage
  • Quick start
  • Presets
  • Features
  • Hooks
    • commit-msg
    • pre-commit
    • pre-push
    • External configuration
• Templates
• Example

Prerequisites

• Lefthook: 2.0.0 or higher

Installation

pnpm add --save-dev @kcconfigs/lefthook

Then install the Git hooks:

lefthook install

Usage

Quick start

Create a lefthook.yaml at your repository root and extend the default preset along with the hooks you need:

# $schema: https://raw.githubusercontent.com/evilmartians/lefthook/v2.0.9/schema.json

extends:
  - ./node_modules/@kcconfigs/lefthook/src/presets/default.yaml

templates:
  pm_cmd: pnpm

Lefthook resolves extends as filesystem paths, not as Node module specifiers, so every entry below is listed relative to the package root and must be prefixed with ./node_modules/@kcconfigs/lefthook/ and suffixed with .yaml in your lefthook.yaml.

For example, presets/default is written as:

extends:
  - ./node_modules/@kcconfigs/lefthook/src/presets/default.yaml

Presets

Presets bundle multiple features together for convenience.

| Name | Path | Description | | --------- | ----------------- | ---------------------------------------------- | | default | presets/default | Enables strict and minimal-output features |

Features

Features configure Lefthook behavior and can be extended individually.

| Name | Path | Description | | ---------------- | ------------------------- | ------------------------------------------------------------------------- | | strict | features/strict | Asserts Lefthook is installed and enforces minimum version 2.0.0 | | minimal-output | features/minimal-output | Limits output to metadata, summary, and execution output for cleaner logs | | debug | features/debug | Disables TTY and prints every output group, including skips and failures |

debug and minimal-output both set output, so extend only one of them.

Hooks

Each hook is a standalone YAML file that can be extended independently. All hooks use the {pm_cmd} template variable for the package manager command (see Templates).

commit-msg

| Hook | Path | Description | | ------------ | ----------------------------- | ------------------------------------------------ | | commitlint | hooks/commit-msg/commitlint | Validates the commit message with commitlint | | textlint | hooks/commit-msg/textlint | Lints and fixes the commit message with textlint |

Both commit-msg hooks set LEFTHOOK=0 so the nested command does not re-enter Lefthook.

pre-commit

Pre-commit hooks run on staged files and autofix where possible (stage_fixed: true).

| Hook | Path | Description | | -------------- | ------------------------------- | ---------------------------------------- | | biome-check | hooks/pre-commit/biome-check | Runs biome check --fix --unsafe | | biome-format | hooks/pre-commit/biome-format | Runs biome format --fix --unsafe | | biome-lint | hooks/pre-commit/biome-lint | Runs biome lint --fix --unsafe | | ls-lint | hooks/pre-commit/ls-lint | Validates file naming conventions | | textlint | hooks/pre-commit/textlint | Lints and fixes *.md and *.txt files | | type-check | hooks/pre-commit/type-check | Runs tsc --noEmit | | vitest | hooks/pre-commit/vitest | Runs the test suite via vitest run |

type-check and vitest do not stage anything; they only gate the commit.

pre-push

Pre-push hooks run broader validation checks before pushing. Unlike pre-commit hooks, these do not autofix files.

| Hook | Path | Description | | -------------- | ----------------------------- | ------------------------------------- | | biome-check | hooks/pre-push/biome-check | Runs biome check (read-only) | | biome-format | hooks/pre-push/biome-format | Runs biome format (read-only) | | biome-lint | hooks/pre-push/biome-lint | Runs biome lint (read-only) | | textlint | hooks/pre-push/textlint | Runs textlint on *.md and *.txt | | type-check | hooks/pre-push/type-check | Runs tsc --noEmit | | vitest | hooks/pre-push/vitest | Runs the test suite via vitest run |

External configuration

The textlint and ls-lint hooks pass repository-level config paths on the command line, so those files must exist:

| Hook | Required files | | ---------- | -------------------------------------------------------------------------- | | textlint | .github/linters/textlintrc.yaml, .github/linters/textlintrc.ignore.txt | | ls-lint | .github/linters/ls-lint.yaml |

Templates

Hooks reference the {pm_cmd} Lefthook template variable so they stay package-manager agnostic. Define it in your lefthook.yaml:

templates:
  pm_cmd: pnpm   # or npm, yarn, bun

Example

A full working configuration used in this monorepo:

# $schema: https://raw.githubusercontent.com/evilmartians/lefthook/v2.0.9/schema.json

extends:
  # Preset (strict + minimal-output)
  - ./node_modules/@kcconfigs/lefthook/src/presets/default.yaml

  # Commit message validation
  - ./node_modules/@kcconfigs/lefthook/src/hooks/commit-msg/commitlint.yaml

  # Pre-commit hooks
  - ./node_modules/@kcconfigs/lefthook/src/hooks/pre-commit/type-check.yaml
  - ./node_modules/@kcconfigs/lefthook/src/hooks/pre-commit/biome-check.yaml
  - ./node_modules/@kcconfigs/lefthook/src/hooks/pre-commit/textlint.yaml
  - ./node_modules/@kcconfigs/lefthook/src/hooks/pre-commit/ls-lint.yaml

  # Pre-push hooks
  - ./node_modules/@kcconfigs/lefthook/src/hooks/pre-push/vitest.yaml

templates:
  pm_cmd: pnpm