[Dev] lint-staged+husky から lefthook への移行を検討しましょう

[KATO-Hiro]

WHY

• husky だと 待ち時間がやや長め
• さまざまな JS ツールが高速な言語に置き換えられて、快適になっている
  • biome、oxlint など

要件

• 高速に処理できる
• lint-staged+husky から移行しやすい
• 継続的にメンテナンスされている

TODO

• lefthook 以外の選択肢がないか調べる
• ツールの絞り込み
• 移行計画を立てる
• 移行
• 動作チェック
• ドキュメントの更新

See

https://github.com/evilmartians/lefthook
https://github.com/StackOneHQ/stackone-ai-node

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Migrate from husky + lint-staged to lefthook to improve pre-commit hook performance and reduce wait times during commits.

Observations

The project currently uses Husky 9.1.7 and lint-staged 16.2.7 for git hook management. The pre-commit hook is configured in .husky/pre-commit to run lint-staged, which executes pnpm format (Prettier write) and pnpm lint (Prettier check + ESLint) on all JavaScript/TypeScript files matching **/*.{js,jsx,ts,tsx}. The project uses pnpm as its package manager and is a SvelteKit application with TypeScript support.

Assumptions

Assumption 1: Handling of auto-fixed files during pre-commit

Options Considered:

• Use lefthook's stage_fixed: true option to automatically stage fixed files
• Manually add && git add {staged_files} to commands

Chosen Option: Use stage_fixed: true option

Rationale: This is lefthook's built-in feature designed for this purpose and aligns with the way the tool is meant to be used. It's cleaner and more declarative than manual git commands.

Assumption 2: Running format and lint in parallel vs sequential

Options Considered:

• Run format and lint sequentially (format first, then lint) to match current behavior
• Run commands in parallel to save time, which is one of lefthook's key advantages

Chosen Option: Run in parallel with parallel: true

Rationale: Since both commands operate on the same staged files and Prettier formatting doesn't typically break ESLint rules, parallel execution will provide faster feedback. This aligns with the ticket's motivation to reduce wait times.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Install lefthook and create configuration

Set up lefthook as a replacement for the existing git hook infrastructure.

Task 1: Install lefthook package

Add lefthook to the project and remove husky/lint-staged dependencies.

• Install lefthook as a dev dependency using pnpm add -D lefthook
• Remove husky and lint-staged from devDependencies in package.json
• Update the prepare script in package.json to run lefthook install instead of husky

Task 2: Create lefthook configuration file

Create a lefthook.yml file at the root of the repository to define the pre-commit hook behavior.

• Configure a pre-commit hook with commands for eslint and prettier targeting staged JavaScript/TypeScript files using glob patterns
• Define two commands: format and lint, each with glob: "*.{js,jsx,ts,tsx}" to match the current file pattern
• Set the format command to run pnpm format {staged_files} targeting staged files only
• Set the lint command to run pnpm lint {staged_files} targeting staged files only
• Enable stage_fixed: true for both commands to automatically add fixed files back to the staging area
• Set parallel: true at the hook level to run both commands simultaneously for faster execution

🤖 Prompt for AI agents

Install lefthook and configure pre-commit hooks to replace husky/lint-staged.

Install lefthook as dev dependency
Remove husky and lint-staged from package.json devDependencies
Update prepare script to run 'lefthook install'
Create lefthook.yml at project root
Configure pre-commit hook with parallel: true
Add format command: pnpm format {staged_files} with glob *.{js,jsx,ts,tsx} and
stage_fixed: true
Add lint command: pnpm lint {staged_files} with glob *.{js,jsx,ts,tsx} and
stage_fixed: true

Phase 2: Update npm scripts and remove husky artifacts

Clean up the existing husky configuration and ensure npm scripts work with lefthook.

Task 1: Modify lint and format scripts

Update the existing npm scripts to work properly when invoked by lefthook with file arguments.

• Verify that the format script (prettier --write .) can accept file arguments from lefthook's {staged_files} placeholder
• Verify that the lint script (prettier --check . && eslint .) can accept file arguments from lefthook's {staged_files} placeholder
• If the scripts cannot accept file arguments in their current form, modify them to support both full project checks and targeted file checks (e.g., split into format:all and format:files, or make them accept file arguments)

Task 2: Remove husky directory and configuration

Clean up all husky-related files and configuration.

• Delete the .husky directory and all its contents
• Remove the lint-staged configuration object from package.json
• Verify that .git/hooks directory will be populated by lefthook on next pnpm install or when developers run lefthook install

🤖 Prompt for AI agents

Clean up husky configuration and ensure npm scripts accept file arguments.

Verify format and lint scripts accept file arguments from lefthook's
{staged_files} placeholder
Modify scripts if needed to support both full project checks and targeted file
checks
Delete .husky directory and all contents
Remove lint-staged configuration from package.json

Phase 3: Verify and document

Ensure the migration is complete and developers understand the new setup.

Task 1: Test the new git hook

Validate that the lefthook configuration works as expected.

• Run lefthook install to set up the git hooks
• Create a test commit with intentionally unformatted JS/TS files to verify the pre-commit hook triggers
• Verify that Prettier formatting and ESLint checks run on staged files
• Verify that auto-fixed files are automatically added to the commit with stage_fixed: true
• Confirm that parallel execution provides faster feedback compared to the previous setup

Task 2: Update documentation if present

Document the change for other developers.

• If a README or CONTRIBUTING file exists, update any references from husky/lint-staged to lefthook
• Add a note that developers should run pnpm install (which triggers the prepare script) or lefthook install directly after pulling these changes to set up their local git hooks
• Document that lefthook can be run manually with lefthook run pre-commit for testing purposes

🤖 Prompt for AI agents

Test the lefthook setup and update documentation.

Run lefthook install to set up git hooks
Test pre-commit hook with intentionally unformatted files
Verify Prettier and ESLint run on staged files
Verify auto-fixed files are staged with stage_fixed: true
Update README or CONTRIBUTING to reference lefthook instead of husky/lint-staged
Document setup instructions for developers (pnpm install or lefthook install)
Document manual testing command: lefthook run pre-commit

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Install lefthook and configure pre-commit hooks to replace husky/lint-staged.

Install lefthook as dev dependency
Remove husky and lint-staged from package.json devDependencies
Update prepare script to run 'lefthook install'
Create lefthook.yml at project root
Configure pre-commit hook with parallel: true
Add format command: pnpm format {staged_files} with glob *.{js,jsx,ts,tsx} and
stage_fixed: true
Add lint command: pnpm lint {staged_files} with glob *.{js,jsx,ts,tsx} and
stage_fixed: true
===============================================================================

Task: 2

Clean up husky configuration and ensure npm scripts accept file arguments.

Verify format and lint scripts accept file arguments from lefthook's
{staged_files} placeholder
Modify scripts if needed to support both full project checks and targeted file
checks
Delete .husky directory and all contents
Remove lint-staged configuration from package.json
===============================================================================

Task: 3

Test the lefthook setup and update documentation.

Run lefthook install to set up git hooks
Test pre-commit hook with intentionally unformatted files
Verify Prettier and ESLint run on staged files
Verify auto-fixed files are staged with stage_fixed: true
Update README or CONTRIBUTING to reference lefthook instead of husky/lint-staged
Document setup instructions for developers (pnpm install or lefthook install)
Document manual testing command: lefthook run pre-commit

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Warning

A plan generation is already in progress. Please wait for it to complete before requesting a new plan.

[coderabbitai]

Caution

CodeRabbit encountered an error during planning. Please try again later.