@savvy-web/lint-staged

@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