Husky Fast

Run comprehensive pre-commit CI checks locally with automatic linting, building, testing, and issue fixing.

When to Use This Command

Run this command when you need to:

• Validate your local changes pass all CI quality gates before committing or pushing
• Run the complete lint, build, typecheck, and test suite in the correct dependency order
• Automatically fix formatting issues and stage corrected files for commit

Consider alternatives when:

• You only need to run a single check like linting (use your package manager script directly)
• You want to set up Husky git hooks for the first time (configure .husky/ manually)

Quick Start

Configuration

Copy
name: husky-fast
type: command
category: automation

Example Invocation

Copy
claude command:run husky-fast --skip-install --fix

Example Output

[Step 0] Environment Setup
  Dependencies: up to date (skipped install)
  .env file: loaded 12 variables

[Step 1] Linting
  Running pnpm lint... PASSED (auto-fixed 3 formatting issues)

[Step 2] TypeScript & Build
  Running typecheck... PASSED
  Running build... PASSED (14.2s)

[Step 3] Test Coverage
  Running test:coverage... PASSED (47/47 tests, 94% coverage)

[Step 4] Package Validation
  sort-package-json... PASSED
  lint:package... PASSED

[Step 5] Staging
  3 files staged for commit
  Checklist: 5/5 steps passed

Core Concepts

Pre-Commit Pipeline Overview

Aspect	Details
Steps	Install, Lint, Build/Typecheck, Test, Package Validation, Stage
Fix Mode	Automatically corrects formatting and sorts package.json
Regression Guard	Re-runs preceding checks after any fix is applied
Safety	Stages files only; never creates commits automatically

Check Workflow

[pnpm install]
      |
[pnpm lint] --fix-->  [auto-format]
      |
[typecheck + build]
      |
[test:coverage]
      |
[sort-package-json + lint:package]
      |
[git add] (stage only, no commit)

Configuration

Parameter	Type	Default	Description
skip-install	boolean	false	Skip dependency installation step
fix	boolean	true	Automatically fix linting and formatting issues
coverage-threshold	number	80	Minimum test coverage percentage required to pass
exclude-submodules	boolean	true	Exclude git submodules in lib/ from staging
verbose	boolean	false	Show full command output for each step

Best Practices

1. Run Before Every Push - Invoke this command as your final validation step before pushing. It mirrors the remote CI pipeline locally so you catch failures without waiting for remote runners.

2. Fix One Step at a Time - When a step fails, the command stops and reports the error. Fix the issue, then re-run from the beginning to ensure your fix does not introduce regressions in earlier steps.

3. Review Auto-Fixed Files - After the command auto-fixes formatting or sorts package.json, review the staged diffs before committing. Automated fixes should always be verified by a human.

4. Source Environment Variables - Ensure your .env file is present and up to date. Tests that depend on environment variables will fail silently or produce misleading results without them.

5. Run Tests Individually for Debugging - When test coverage fails, run individual test packages one by one to isolate the failing suite. Bulk test runs can mask which package introduced the regression.

Common Issues

1. Tests Timeout When Using Normal Test Command - Always use test:coverage instead of test. The normal test command hangs on certain configurations. The coverage variant includes proper timeout handling.

2. Snapshot Tests Fail After Refactoring - Do not blindly update snapshots. Examine the diff to understand why the snapshot changed, form a hypothesis, and only then update with --updateSnapshot.

3. Submodule Files Accidentally Staged - Git submodules in lib/ folders must be excluded from staging. If they appear in git status, the command skips them, but verify with git diff --cached before committing.