husky add Deprecation and Modern Alternatives for Git Hooks

As of Husky version 9.0.0 (released in 2024), the husky add command is deprecated. This change has led to some confusion for developers accustomed to older workflows for setting up Git hooks, especially since many existing tutorials still reference the old command. This guide will clarify why the change occurred and detail the current methods for managing Git hooks with Husky.

Open Table of contents

Why Is husky add Deprecated?
What to Use Instead of husky add?
Key Notes for 2025
Troubleshooting Common Issues
Workaround for Older Projects
Why This Matters for Modern Development
Resources

Why Is `husky add` Deprecated?

Husky, a widely-used tool for managing Git hooks, underwent significant changes in version 9 to simplify its API and enhance cross-platform compatibility. The primary goal was to make hook setup more explicit and straightforward.

The husky add command, which was previously used to generate hook scripts (e.g., npx husky add .husky/commit-msg 'npx commitlint --edit $1'), was removed in favor of a more manual approach. This shift gives developers finer-grained control over their hook scripts and reduces the tool’s “magic,” making the process more transparent.

What to Use Instead of `husky add`?

With Husky v9 and later, you manually create hook files within the .husky/ directory. The husky init command can help bootstrap this setup. Here’s how to perform common tasks previously done with husky add, based on current best practices and information from resources like the Fix Code Bugs blog:

1. Initialize Husky

If you’re setting up Husky in a new project or migrating, start with initialization:

Run the command:
```
npx husky init
```
This command performs two main actions:
1. Creates the .husky/ directory.
2. Adds a prepare script to your package.json, which ensures Husky is set up correctly after npm install.
3. Creates a default .husky/pre-commit hook file as an example.

Your package.json will be updated similar to this:

{
  "scripts": {
    "prepare": "husky"
  }
}

2. Create a Hook Manually

Instead of husky add, you’ll now directly create and populate the hook files.

For example, to create a commit-msg hook for linting commit messages with Commitlint:
```
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg
```
(Note: The \$1 ensures that $1 is written literally to the file, to be interpreted by the shell when the hook runs. On some systems, you might use '$1' or ensure your shell doesn’t expand it.)
This command creates a file named commit-msg inside the .husky/ directory and writes the Commitlint command into it. This replaces the old npx husky add .husky/commit-msg 'npx commitlint --edit $1'.

3. Make the Hook Executable (Linux/macOS)

Git requires hook scripts to be executable.

After creating a hook file, make it executable:
```
chmod +x .husky/commit-msg
```
(Replace .husky/commit-msg with the path to your specific hook file.)
This step is crucial on Unix-like systems. For Windows, Git handles executability differently, often not requiring chmod.

4. Example for a `pre-commit` Hook

To run tasks like linters (e.g., ESLint, Prettier) or tests before a commit:

Create or edit the .husky/pre-commit file:

echo "npm run lint" > .husky/pre-commit
chmod +x .husky/pre-commit

If you’re using a tool like lint-staged to lint only staged files:

echo "npx lint-staged" > .husky/pre-commit
chmod +x .husky/pre-commit

Key Notes for 2025

As you work with Husky v9+ in 2025, keep these points in mind:

Husky v9 Breaking Changes: Beyond husky add, Husky v9 also removed or changed other features. For instance, husky install is effectively replaced by the prepare script triggered by husky or husky init. Also, Husky no longer automatically adds shebang lines (e.g., #!/usr/bin/env sh or #!/bin/sh) to hook scripts. You need to ensure your scripts start with an appropriate shebang if they require a specific interpreter. You might need to update existing hooks to align with these changes.
Cross-Platform Compatibility: Ensure your hook scripts are POSIX-compliant to maintain compatibility across different operating systems, especially Windows. Using Bash-specific syntax might lead to command not found errors for some users.
Manual Script Content: You are now fully responsible for the content of your hook scripts, including the shebang. A common shebang is #!/bin/sh.

Troubleshooting Common Issues

If your Husky hooks aren’t running as expected:

Verify Husky Installation: Ensure Husky is installed as a dev dependency:

npm install --save-dev husky
# or
yarn add --dev husky
# or
pnpm add --save-dev husky

Check prepare Script: Confirm that the prepare script ("prepare": "husky") is present in your package.json. This script is crucial for setting up Husky after installation or when cloning the repository.
Hook Executability: Double-check that your hook files in the .husky/ directory are executable (see chmod +x above), especially on macOS and Linux.
Hook File Content: Ensure the commands within your hook scripts are correct and that they start with an appropriate shebang (e.g., #!/bin/sh).
Git Configuration: Verify that Git is configured to use the .husky directory for hooks (git config core.hooksPath). The husky init command should set this up, but it’s worth checking if issues persist.
Monorepo Setups: For monorepos, ensure you run husky init in the root directory of your project, or correctly specify the path if using advanced configurations.
Consult Documentation: Refer to the official Husky documentation for the latest guidance and troubleshooting tips.

Workaround for Older Projects

If you are working on an older project that heavily relies on the deprecated husky add command and updating the entire setup is not immediately feasible:

Downgrade to Husky v8: You can temporarily downgrade Husky to version 8.x.x.
- Modify your package.json:
```
"devDependencies": {
  "husky": "^8.0.3" // Or another v8 release
}
```
- Then run npm install (or yarn install / pnpm install).
- This will restore the deprecated commands but is not recommended for new projects or long-term maintenance due to missing out on v9+ improvements and support.
Update Scripts Gradually: The recommended approach is to adapt your project’s scripts to the new Husky v9+ workflow to ensure ongoing compatibility and benefit from the latest features.

Why This Matters for Modern Development

Understanding changes like the deprecation of husky add is important for maintaining robust development workflows. As noted by resources like the Fix Code Bugs blog, clear error handling and up-to-date tooling practices are essential. By manually creating and managing hook files, developers gain more explicit control over their Git automation, reducing reliance on abstracted commands and aligning with more transparent development practices prevalent in 2025. This direct control can also make debugging hook-related issues simpler.

Resources

For more detailed information and official guidance, refer to the following resources:

Official Husky Documentation: https://typicode.github.io/husky/
Husky Get Started Guide: https://typicode.github.io/husky/get-started.html
Husky How-To (Cross-platform hooks): https://typicode.github.io/husky/how-to.html
Stack Overflow Discussion on husky add deprecation: https://stackoverflow.com/questions/78173983/husky-add-command-is-deprecated
GitHub Issue on husky add removal: https://github.com/typicode/husky/issues/1476
Blog Post on Migrating Husky v8 to v9: https://remarkablemark.org/blog/2024/02/04/how-to-migrate-from-husky-8-to-9/
Article on Commitlint & Husky Setup (may reference older versions but contextually useful):
- https://peterabraham.com/article/how-to-install-commitlint-&-husky
- https://medium.com/@abpeter14/how-to-install-commitlint-husky-2024-f1157f14006f
Zenn Article on Husky in Monorepos (Japanese, but translatable): https://zenn.dev/otomoti_27/articles/692e1308ce849b
Fix Code Bugs Blog (General Reference): https://fix-code-bugs.web.app/