Setting Up Husky and lint-staged in Your Next/React Project

Code quality tools like ESLint and Prettier are fantastic for maintaining clean, consistent code. But they're only effective when developers remember to use them. What if you could ensure that code is automatically linted and formatted before it's committed to your repository? That's where Husky and lint-staged come in.

In this guide, I'll walk you through setting up Husky and lint-staged in your React/Next.js project to automate code quality checks and prevent problematic code from entering your codebase.

What are Husky and lint-staged?

Husky is a tool that makes setting up Git hooks easy. Git hooks are scripts that run automatically when specific Git events occur, such as committing or pushing code. lint-staged is a tool that runs linters against staged Git files. This means you can run your linters and formatters only on the files that you're about to commit, rather than the entire codebase, which is much faster.

Together, these tools create a powerful pre-commit workflow that ensures code meets your team's standards before it's committed.

Benefits of Using Husky and lint-staged

Consistency: Ensures all committed code follows your team's style guidelines
Automation: Runs formatting and linting automatically, so developers don't have to remember
Speed: Only checks files that are staged for commit, not the entire codebase
Prevention: Stops problematic code from entering the repository in the first place
Team Harmony: Reduces style-related debates in code reviews

Installation

Let's start by installing the necessary packages:

npm install --save-dev husky lint-staged

husky: Manages Git hooks.
lint-staged: Filters staged files and runs tasks on them.

Setting Up Husky

First, we need to initialize Husky in our project. This will create the necessary Git hook scripts:

npx husky init

This command:

Creates a .husky directory in your project root.
Adds a sample pre-commit hook file (.husky/pre-commit).
Updates your package.json with a prepare script like this:

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

The prepare script runs automatically after npm install, so Husky will be set up for everyone working on the project.

And .husky directory will look like this:

.husky
├── _
│   ├── applypatch-msg
│   ├── commit-msg
│   ├── h
│   ├── husky.sh
│   ├── post-applypatch
│   ├── post-checkout
│   ├── post-commit
│   ├── post-merge
│   ├── post-rewrite
│   ├── pre-applypatch
│   ├── pre-auto-gc
│   ├── pre-commit
│   ├── pre-merge-commit
│   ├── pre-push
│   ├── pre-rebase
│   └── prepare-commit-msg
└── pre-commit

Step 3: Configure the Pre-Commit Hook

Edit the .husky/pre-commit file to run lint-staged. Replace its contents with:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

What This Does:

The shebang (#!/usr/bin/env sh) ensures the script runs in a POSIX-compliant shell.
The . "$(dirname ...)" line sources Husky’s helper script.
npx lint-staged triggers lint-staged to process staged files.

Step 4: Configure Lint-Staged

Add a lint-staged configuration to your package.json:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

Alternatively, you can create a separate lint-staged.config.js file:

module.exports = {
  "src/**/*.{js,jsx,ts,tsx}": [
    "eslint --fix",
    "git add"
  ]
};

Explanation of the Configuration:

"*.{js,jsx,ts,tsx}": Targets JavaScript, JSX, TypeScript, and TSX files that are staged for commit.
"eslint --fix": Runs ESLint with automatic fixing on those files.
"prettier --write": Formats the files with Prettier.

The tasks run sequentially, so Prettier formatting happens after ESLint fixes. If either task fails (e.g., unfixable linting errors), the commit is aborted.

Step 5: Test the Setup

Make some changes to a .js or .tsx file (e.g., add inconsistent formatting or a linting error).

// src/app/about/page.tsx
export default function About() {
      let x = 10
  console.log(x)

  return (
    <div className="">
      <h1 className="">About</h1>
    </div>
  )
}

Stage the changes:
```
git add .
```

Attempt to commit:

git commit -m "Test Husky and lint-staged"

Husky will trigger lint-staged, which:

Runs ESLint to fix linting issues.
Runs Prettier to format the code.
Updates your staged files with the fixes.
Allows the commit to proceed if everything passes, or aborts it if there are unfixable errors.

Make the test for case abord commit:

// src/app/about/page.tsx
export default function About() {
    let x = 10

  return (
    <div className="">
      <h1 className="">About</h1>
    </div>
  )
}

'x' is declared but its value is never read

You will see the error:

error  'x' is assigned a value but never used  @typescript-eslint/no-unused-vars

husky - pre-commit script failed (code 1)

and the commit will be aborted.

Step 6: Enhance Your Workflow (Optional)

Add More File Types

If your project includes CSS, Markdown, or JSON files, extend the lint-staged config:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{css,md,json}": ["prettier --write"]
  }
}

Integrate with Existing Scripts

If you have npm scripts like lint and format (e.g., eslint . or prettier --write "**/*"), you can align lint-staged with them. However, lint-staged already scopes to staged files, so keep it simple and targeted.

Skip Hooks When Needed

To bypass the pre-commit hook temporarily:

git commit --no-verify -m "Quick commit"

Use this sparingly, as it skips all checks!

Troubleshooting

Husky Not Running: Ensure your Git repository is initialized (git init) and the prepare script is in package.json. Run npm run prepare manually to reinstall hooks if needed.
Permission Issues: If the hook isn’t executable, run:
```
chmod +x .husky/pre-commit
```
Lint-Staged Fails Silently: Check your ESLint/Prettier configs for errors, and ensure the file extensions in lint-staged match your project.

Benefits of This Setup

Efficiency: Only processes staged files, not the entire codebase.
Consistency: Enforces linting and formatting rules before code reaches the repository.
Team-Friendly: Works out of the box for all developers after npm install.
CI/CD Integration: Reduces the burden on continuous integration by catching issues locally.

Conclusion

With Husky and lint-staged in place, your NextJS/React project now has a robust gatekeeper for code quality. Pair this with a solid ESLint and Prettier setup, and you’ll spend less time debating code style and more time building features. Try it out, tweak the lint-staged config to fit your needs, and enjoy cleaner commits!