Resolving lint-staged Not Running on Pre-commit: An In-depth Analysis and Practical Guide Based on Husky Version Compatibility

Problem Background and Phenomenon Analysis

In modern front-end development workflows, code quality tools like Prettier and ESLint are often integrated with Git hooks via lint-staged to enable automatic formatting and checking before commits. However, developers frequently encounter issues where lint-staged does not run on pre-commit hooks, even with configurations proven effective in other projects. Based on the Q&A data, users report correct setups in package.json for scripts and lint-staged, but prettier fails to trigger on commit, highlighting the fragility of toolchain integration.

Core Cause: Husky Version Compatibility and Hook Installation Mechanism

Synthesizing high-scoring answers, the root cause often centers on Husky versions. Answer 5, as the best answer (score 10.0), indicates that reinstalling Husky can resolve the issue, suggesting anomalies in dependency state or hook installation. Answer 1 adds that Husky v4 is more reliable, while v6 may not trigger, and it's essential to check git configuration core.hooksPath—if set, clear it with git config --unset core.hookspath to avoid path conflicts. Answer 2 further explains that Husky sometimes fails to add hooks correctly, recommending installing v4 first to ensure hook setup, then upgrading to the latest version for updates.

Systematic Solutions and Practical Steps

Based on Answer 5 as the primary reference, combined with other answers, we distill the following repair process:

1. Verify Current Configuration: First, check the scripts and lint-staged settings in package.json to ensure consistency with examples. Run git config core.hooksPath; if output is non-empty, execute git config --unset core.hookspath to reset Git hook paths.
2. Reinstall Husky: As per Answer 5, uninstalling and reinstalling Husky can fix corrupted dependencies or hooks. Use commands npm uninstall husky followed by npm install -D husky. Answer 4 suggests downgrading to v4 (npm install -D husky@4), which often resolves compatibility issues.
3. Manual Hook Installation: If reinstallation fails, refer to Answer 2; for Husky v6, manually add hooks: npx husky add .husky/pre-commit "npx lint-staged". Ensure to run npm run prepare or yarn prepare to activate hooks.
4. Use mrm Tool: Answer 3 notes that npx mrm lint-staged might only configure without installing dependencies, so first run npm i -D husky lint-staged, then the mrm command.
5. Rebuild Dependencies: Answer 6 recommends running npm rebuild or npm rebuild --update-binary (for yarn) to fix binary files in node_modules.

Code Examples and Configuration Details

To clarify core concepts, we rewrite a typical configuration example. In package.json:

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "*.{js,json,css,scss,html,md}": [
      "prettier --write",
      "git add"
    ]
  },
  "devDependencies": {
    "husky": "^4.3.8",
    "lint-staged": "^10.5.4",
    "prettier": "^2.3.0"
  }
}

This configuration uses Husky v4 to ensure compatibility. lint-staged defines running prettier and git add for multiple file types. Note that in text nodes, such as when describing HTML tags, special characters must be escaped: for example, when discussing the difference between the <br> tag and characters, <br> is escaped as text content to avoid parsing errors.

Preventive Measures and Best Practices

To prevent future issues, it is advisable to: keep Husky and lint-staged updated but test v4 for stability first; use npx mrm lint-staged during project initialization and confirm dependency installation; regularly check git configuration and hook status. Through a systematic approach, developers can efficiently integrate code quality tools and enhance the development experience.