@savvy-web/lint-staged

Composable, configurable lint-staged handlers for pre-commit hooks. Stop duplicating lint-staged configs across projects -- use reusable handlers with sensible defaults and easy customization.

Features

• Composable handlers for Biome, Markdown, YAML, TypeScript, and more
• Zero-config presets for instant setup
• CLI tool (savvy-lint) to bootstrap and validate your configuration
• Workspace-aware TSDoc validation for public APIs
• Shareable Biome configuration via @savvy-web/lint-staged/biome/silk.jsonc
• Static class API with excellent TypeScript and TSDoc support

Installation

# Install the package and required peer dependencies
npm install -D @savvy-web/lint-staged lint-staged husky

# For Biome handler (recommended)
npm install -D @biomejs/biome

# For Markdown handler
npm install -D markdownlint-cli2

Quick Start

Use the CLI to bootstrap your configuration:

npx savvy-lint init --preset standard

Or configure manually with a preset:

// lint-staged.config.ts
import { Preset } from '@savvy-web/lint-staged';

export default Preset.standard();

Or compose individual handlers:

// lint-staged.config.ts
import { PackageJson, Biome, Markdown, Yaml } from '@savvy-web/lint-staged';

export default {
  [PackageJson.glob]: PackageJson.handler,
  [Biome.glob]: Biome.handler,
  [Markdown.glob]: Markdown.handler,
  [Yaml.glob]: Yaml.handler,
};

Presets

| Preset | Handlers | | --- | --- | | minimal() | PackageJson, Biome | | standard() | + Markdown, Yaml, PnpmWorkspace, ShellScripts | | silk() | + TypeScript |

Available Handlers

| Handler | Files | Description | | --- | --- | --- | | PackageJson | **/package.json | Sort and format with Biome | | Biome | *.{js,ts,jsx,tsx,json,jsonc} | Format and lint | | Markdown | **/*.{md,mdx} | Lint with markdownlint-cli2 | | Yaml | **/*.{yml,yaml} | Format (Prettier) and validate (yaml-lint) | | PnpmWorkspace | pnpm-workspace.yaml | Sort and format | | ShellScripts | **/*.sh | Manage permissions | | TypeScript | *.{ts,cts,mts,tsx} | TSDoc validation + typecheck |

CLI

The savvy-lint CLI helps bootstrap, validate, and format your setup:

savvy-lint init              # Bootstrap hooks, config, and tooling
savvy-lint init --preset silk --force  # Overwrite with silk preset
savvy-lint check             # Validate current configuration
savvy-lint check --quiet     # Warnings only (for postinstall)
savvy-lint fmt package-json  # Sort package.json fields
savvy-lint fmt yaml          # Format YAML files with Prettier
savvy-lint fmt pnpm-workspace  # Sort and format pnpm-workspace.yaml

Claude Code Plugin

A companion Claude Code plugin is available that automatically injects code quality context (Biome, markdownlint, and TypeScript conventions) at session start.

# Add the Savvy Web plugin marketplace (one-time setup)
/plugin marketplace add savvy-web/systems

# Install the lint-staged plugin for this project
/plugin install lint-staged@savvy-web-systems --scope project

Documentation

• Handler Configuration -- Detailed options for each handler
• Configuration API -- createConfig and Preset APIs
• CLI Reference -- savvy-lint init, check, and fmt
• Utilities -- Command, Filter, and advanced utilities
• Migration Guide -- Migrating from raw lint-staged configs

Contributing

Contributions welcome! See CONTRIBUTING.md for setup and guidelines.

License

MIT