How to Use Husky and Lint-Staged with Git Hooks: Automate Code Quality & Formatting

One way to ensure code quality is by using Git hooks in conjunction with tools like Husky and lint-staged. These tools allow you to automate code quality checks and formatting processes, preventing bad code commits and improving overall development productivity. In this comprehensive guide, we will explore how to set up and use Husky and lint-staged together, providing step-by-step instructions, troubleshooting tips, and best practices.

Table of Contents

1. Introduction to Git Hooks

2. Overview of Husky

3. Understanding Lint-Staged

4. Setting Up Git Hooks with Husky and Lint-Staged

5. Pre-Commit Hooks: Automating Code Quality Checks

6. Pre-Push Hooks: Ensuring Code Quality Before Pushing

7. Troubleshooting Common Issues

8. Best Practices for Using Husky and Lint-Staged

9. Enhancing Developer Productivity with Git Hooks

10. Advanced Configuration Options

11. Alternatives to Husky and Lint-Staged

12. Conclusion

Now, let's dive into each section in detail to learn how to harness the power of Husky and lint-staged for automated code quality and formatting.

1. Introduction to Git Hooks

What are Git Hooks?

Git hooks are scripts that can be executed automatically before or after specific Git events, such as committing changes or pushing code to a remote repository. These hooks allow you to perform custom actions or checks on your codebase, ensuring code quality and preventing common issues.

Why Use Git Hooks for Code Quality?

Git hooks play a vital role in improving code quality and maintaining consistency within a development team. By running automated checks and tests before committing or pushing code, you can catch potential issues early on and prevent them from being introduced into the codebase. This helps in avoiding bugs, enforcing coding standards, and ensuring a clean and reliable code repository.

2. Overview of Husky

What is Husky?

Husky is a popular npm package that simplifies the setup and management of Git hooks. It provides an easy-to-use interface for configuring hooks and running scripts based on specific Git events. With Husky, you can automate code quality checks, run tests, and enforce coding standards seamlessly.

Benefits of Using Husky

By incorporating Husky into your development workflow, you can reap several benefits:

1. Automated Code Quality Checks: Husky allows you to run scripts or tools for linting, formatting, and testing your code before committing or pushing, ensuring that only high-quality code makes it into the repository.

2. Improved Developer Productivity: With automated checks in place, developers can focus on writing code rather than manually running checks. This saves time and reduces the risk of human error.

3. Consistent Codebase: Husky enforces coding standards and formatting rules, ensuring that all team members follow the same conventions. This leads to a more consistent and maintainable codebase.

4. Easy Integration with CI/CD Pipelines: Husky hooks can be seamlessly integrated into continuous integration/continuous deployment (CI/CD) pipelines, allowing for even more comprehensive code quality checks before deployment.

3. Understanding Lint-Staged

Introduction to Lint-Staged

Lint-Staged is an npm package designed to run scripts on Git staged files. It allows you to selectively apply code quality checks, formatting, and other tasks only to the files that are staged for the next commit. This targeted approach helps in optimizing the execution time of these checks and prevents unnecessary processing of unchanged files.

How Lint-Staged Works

When you run the git commit command, Git stages the modified files that are part of the commit. Lint-Staged operates on these staged files and runs the specified scripts or commands against them. This ensures that only the relevant files are processed, making the code quality checks and formatting more efficient.

Configuring Lint-Staged

To configure Lint-Staged, you need to define the scripts or commands you want to run on the staged files. This configuration is typically specified in the lint-staged section of your project's package.json file. You can specify different scripts for different file types or apply the same script to all staged files.

Here's an example configuration in a package.json file:

"lint-staged": {
  "*.{js,jsx}": ["eslint --fix", "git add"],
  "*.{css,scss}": ["stylelint --fix", "git add"],
  "*.{json,md}": ["prettier --write", "git add"]
}

In the above configuration, we have specified different scripts for JavaScript/JSX files, CSS/SCSS files, and JSON/Markdown files. The scripts run the respective linting or formatting tools and then add the modified files back to the staging area using git add.

4. Setting Up Git Hooks with Husky and Lint-Staged

Now that we have a basic understanding of Git hooks, Husky, and Lint-Staged, let's proceed with setting up the hooks in your project. The following steps will guide you through the installation and configuration process.

Installing Husky and Lint-Staged

Before you can start configuring Git hooks, you need to install Husky and Lint-Staged as development dependencies in your project. Open your terminal and navigate to your project's directory. Then run the following command:

npm install husky lint-staged --save-dev

This command installs both Husky and Lint-Staged and adds them to your project's package.json file as devDependencies.

Configuring Husky for Git Hooks

Once the installation is complete, you can proceed with configuring Husky to run Git hooks in your project. Husky allows you to define hooks by adding a husky section in your package.json file. Open the package.json file in your preferred text editor, and add the following code:

"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
}

In the above configuration, we have defined a pre-commit hook that runs the lint-staged command. This means that every time you commit changes, Husky will automatically trigger Lint-Staged to run the specified scripts on the staged files.

Defining Lint-Staged Rules

To define the scripts or commands you want to run on the staged files, you need to create a .lintstagedrc file in the root of your project. This file will contain the configuration for Lint-Staged.

Here's an example .lintstagedrc file:

{
  "*.{js,jsx}": ["eslint --fix", "git add"],
  "*.{css,scss}": ["stylelint --fix", "git add"],
  "*.{json,md}": ["prettier --write", "git add"]
}

In this example, we have defined different scripts for JavaScript/JSX files, CSS/SCSS files, and JSON/Markdown files. The scripts run the respective linting or formatting tools and then add the modified files back to the staging area using git add.

With Husky and Lint-Staged properly configured, you are now ready to automate code quality checks and formatting with Git hooks.

5. Pre-Commit Hooks: Automating Code Quality Checks

One of the most common use cases for Git hooks is to run code quality checks before making a commit. This ensures that the committed code meets the defined standards and conventions. By automating these checks, you can catch potential issues early on and maintain a clean and reliable codebase.

Preparing Your Project for Pre-Commit Hooks

Before you can start writing pre-commit hooks, make sure you have the necessary tools installed and configured in your project. For example, if you want to run ESLint for JavaScript linting, make sure you have ESLint installed and have a .eslintrc file that defines the linting rules.

You can install the necessary tools using npm or yarn:

npm install eslint --save-dev

Writing Pre-Commit Scripts

To write a pre-commit script, you need to define the script in the husky.hooks section of your package.json file. Open the package.json file and add the following code:

"husky": {
  "hooks": {
    "pre-commit": "lint-staged && npm test"
  }
}

In the above configuration, we have added the pre-commit hook that runs lint-staged and npm test sequentially. This means that before each commit, Husky will run Lint-Staged to format the staged files and then run your test suite to ensure the code passes all the tests.

Running Linting Tools with Pre-Commit Hooks

To run linting tools as part of your pre-commit checks, you need to define the necessary linting scripts in your project's configuration. For example, if you are using ESLint for JavaScript linting, you can add an ESLint script to your package.json file:

"scripts": {
  "lint:js": "eslint ."
}

Then, in your lint-staged configuration, you can include the ESLint script:

{
  "*.js": "npm run lint:js"
}

In this example, the pre-commit hook will run ESLint on all staged JavaScript files, ensuring that the code adheres to the defined linting rules.

By combining pre-commit hooks with lint-staged, you can automate code quality checks and ensure that only clean and properly formatted code is committed to your repository.

6. Pre-Push Hooks: Ensuring Code Quality Before Pushing

Pre-push hooks provide an additional layer of code quality checks before pushing your code to a remote repository. These hooks allow you to run tests, perform additional linting, or even enforce specific rules or policies before pushing changes. By catching issues before they reach the remote repository, you can maintain a more reliable and stable codebase.

Introduction to Pre-Push Hooks

Pre-push hooks are executed before the git push command is executed. They allow you to run custom scripts or commands to validate the code and ensure it meets the defined standards. Pre-push hooks are useful for running tests, performing additional linting, or even triggering build processes before pushing changes.

Configuring Pre-Push Hooks with Husky

To configure pre-push hooks with Husky, you need to define the pre-push hook in your husky.hooks section of the package.json file. Open the package.json file and add the following code:

"husky": {
  "hooks": {
    "pre-push": "npm run lint && npm test"
  }
}

In the above configuration, we have defined the pre-push hook to run the lint and test scripts sequentially. This means that before each push, Husky will run these scripts to ensure that the code passes linting checks and all tests are passing.

Running Tests and Other Checks with Pre-Push Hooks

In addition to running tests, you can include other checks or scripts in your pre-push hooks to further ensure code quality. For example, you can include additional linting scripts, security scans, or even trigger a build process to generate the production-ready code.

To add custom checks or scripts, define them in your project's configuration or package.json file. Then, include the necessary commands in the pre-push hook configuration.

By combining pre-push hooks with Husky, you can enforce code quality checks before pushing changes, reducing the risk of introducing issues into the remote repository.

7. Troubleshooting Common Issues

While using Husky and Lint-Staged together can greatly improve code quality and automate code formatting, you may encounter some common issues along the way. Here, we will discuss a few common problems and their solutions.

Common Errors and Their Solutions

1. Husky hooks are not running: If the hooks are not running as expected, double-check that you have properly configured Husky in your package.json file and that the necessary dependencies are installed.

2. Lint-Staged is not formatting files: Ensure that the patterns specified in your .lintstagedrc file match the files you want to format. Also, check that the formatting tools (e.g., ESLint, Prettier) are properly installed and configured.

3. Pre-commit or pre-push hooks are taking too long: If the hooks are taking too long to execute, consider optimizing your scripts or excluding unnecessary checks. You can also parallelize the execution of tasks using tools like concurrently or running the hooks in the background.

Debugging Hooks with Git Logs

To debug issues with Git hooks, you can check the Git logs to see the output and any error messages generated by the hooks. Use the following command to view the logs:

git log --grep=<hook-name>

Replace <hook-name> with the name of the hook you want to debug (e.g., pre-commit, pre-push). The logs will provide insights into what happened during the execution of the hook and help identify any issues.

Handling Conflicts and Merge Issues

When working with Git hooks, conflicts or merge issues can sometimes arise due to changes in the hook scripts or configuration. To resolve conflicts, carefully review the changes made to the hooks and merge them appropriately. If necessary, consult with your team members or refer to the Git documentation for conflict resolution strategies.

By troubleshooting and resolving common issues, you can ensure the smooth functioning of your Git hooks setup and maintain a clean and reliable codebase.

8. Best Practices for Using Husky and Lint-Staged

To make the most of Husky and Lint-Staged, it's important to follow best practices and adhere to established conventions. Here are some best practices to help you optimize your Git hooks setup:

Organizing Hook Scripts

1. Keep hook scripts concise and focused on specific tasks.

2. Modularize hook scripts by separating them into smaller scripts or functions.

3. Use meaningful names for hook scripts to make it easier to understand their purpose.

Collaborating with Team Members

1. Ensure all team members have Husky and Lint-Staged installed and configured in their local environments.

2. Share the Git hooks configuration with the team through version control to ensure consistent setups.

3. Communicate and document any changes made to the hooks or their scripts to keep everyone informed.

Integrating with CI/CD Pipelines

1. Incorporate Git hooks into your CI/CD pipelines to perform additional checks and tests before deployment.

2. Ensure the same code quality checks and formatting rules are enforced both locally and in the CI/CD pipeline to maintain consistency.

Following these best practices will help you maintain a clean and efficient workflow, promoting code quality and collaboration within your development team.

9. Enhancing Developer Productivity with Git Hooks

By automating code quality checks and formatting processes with Git hooks, you can significantly enhance developer productivity. Here are some key ways Git hooks can boost productivity:

Time-Saving Benefits of Automated Checks

1. Reduce the time spent manually running code quality checks and tests.

2. Catch issues early on, preventing them from being propagated to other team members or downstream processes.

3. Enable developers to focus on writing code rather than worrying about code quality.

Streamlining Code Review Processes

1. Ensure that code reviews focus on higher-level architectural and design decisions rather than basic code quality issues.

2. Facilitate smoother and quicker code reviews by reducing the number of issues to be addressed.

Improving Codebase Consistency

1. Enforce coding standards and formatting rules consistently across the entire codebase.

2. Minimize inconsistencies and style conflicts between different team members' code.

3. Enhance code readability and maintainability for future developers.

With Git hooks, you can create a more streamlined and efficient development process, allowing developers to focus on writing high-quality code and delivering value to their projects.

10. Advanced Configuration Options

While the basic configuration of Husky and Lint-Staged covers most use cases, there are advanced configuration options available for fine-tuning your Git hooks setup. Here are a few examples:

Customizing Husky Hooks

1. Define custom hooks to run scripts for specific events other than pre-commit or pre-push.

2. Configure hooks to run in parallel or in a specific order by modifying the husky.hooks section.

Extending Lint-Staged Functionality

1. Add additional file patterns and scripts to the .lintstagedrc file to include more specific checks or formatting tasks.

2. Integrate other code quality tools or custom scripts into Lint-Staged to further enhance your codebase's quality.

Exploring Additional Git Hooks

1. Investigate other Git hooks provided by Git to automate other aspects of your development workflow, such as pre-receive or post-receive hooks.

2. Explore third-party Git hooks libraries or tools that provide additional functionality for specific use cases.

By exploring these advanced configuration options, you can tailor your Git hooks setup to meet your project's specific requirements and optimize your development process.

11. Alternatives to Husky and Lint-Staged

While Husky and Lint-Staged are popular choices for managing Git hooks, there are other alternatives available that may better suit your needs. Here are a few examples:

1. pre-commit: A flexible framework for managing and maintaining Git hooks in multi-language projects.

2. pre-push: A tool that allows you to run checks and tests before pushing code to a remote repository.

3. git-hooks: A collection of Git hooks written in Bash that cover a wide range of use cases.

When choosing an alternative, consider factors such as language support, ease of configuration, and the specific requirements of your project. Experiment with different tools to find the one that best fits your development workflow.

12. Conclusion

In this comprehensive guide, we have explored how to use Husky and Lint-Staged together to automate code quality checks and formatting processes with Git hooks. By setting up pre-commit and pre-push hooks, you can ensure that only high-quality code makes it into your repository, improving collaboration, and reducing the risk of introducing bugs or style inconsistencies.

Throughout the guide, we discussed the benefits of using Husky and Lint-Staged, troubleshooting common issues, and provided best practices for optimizing your Git hooks setup. We also highlighted the importance of enhancing developer productivity and explored advanced configuration options and alternatives to Husky and Lint-Staged.

By incorporating Git hooks into your development workflow, you can streamline code quality checks, enforce coding standards, and maintain a clean and reliable codebase. Embrace the power of Husky and Lint-Staged to automate code quality and formatting, and take your development process to the next level.