Husky + Prettier + lint-staged Setup for Next.js

Most code quality issues are caught too late: in code review, or worse, in production. Husky, Prettier, and lint-staged give you an automatic check on every single commit, right on your machine, before the code ever leaves your editor.

This guide walks through the full setup for a Next.js project using the current versions of all three tools. If you've tried this before with a guide from 2022 and it didn't work, it's probably because Husky changed its configuration format in v9.

If your project already had Husky before v9, the upgrade is mostly deletion. Husky v9 removed the shebang line, the husky.sh source line, and the husky install command. Hook files are now plain shell scripts with no boilerplate at all.

The migration itself is three commands. Upgrade the package, strip the old preamble from each hook file, and swap the prepare script.

Under the hood, v9 points Git at .husky/_ rather than .git/hooks by setting core.hooksPath. That directory is generated by the prepare script and should be git-ignored. Husky writes a .husky/_/.gitignore for you, so in most projects there is nothing to do.

If you keep your own prepare script for other setup work, chain husky into it rather than replacing it. A prepare script that does not call husky means hooks silently stop installing for everyone who clones the repo.

ESLint 9 replaced .eslintrc.json with a flat config file, eslint.config.mjs, and Next.js 16 dropped the next lint wrapper entirely in favour of calling the ESLint CLI directly. Both changes affect what you put in your lint-staged config.

The important practical difference is how ESLint treats a file that you pass explicitly on the command line but that your config ignores. Under flat config, ESLint emits a warning instead of quietly skipping the file. Because lint-staged passes staged file paths as arguments, any staged file inside an ignored directory produces that warning, and if you run with --max-warnings=0 the commit fails for no real reason.

One more overlap to remove: if any of your ESLint rules control formatting (quote style, semicolons, indentation), they will fight Prettier and produce a commit that flips back and forth. Install eslint-config-prettier and put it last in the config array so it turns those rules off.

Type-aware rules deserve a separate warning. Enabling projectService or parserOptions.project makes ESLint load the whole TypeScript program on every run, which turns a 300ms pre-commit hook into a 12 second one. If you want type-aware linting, keep it out of the commit hook and run it in CI. The same trade-off shows up in the TypeScript 7 tooling breakage roundup.

A pre-commit hook has one hard constraint: developers must not notice it. Once it crosses roughly two seconds, people start reaching for --no-verify out of habit, and at that point the hook has stopped protecting anything.

Most slow hooks are slow for one of four reasons. Work through them in this order, because the fixes get progressively more invasive.

lint-staged already runs different glob patterns concurrently, so splitting work across more patterns does not usually help. What does help is reducing how many times a binary starts up, since Node process startup is a fixed cost you pay per invocation.

If you genuinely need a project-wide check before code leaves the machine, use a pre-push hook. Pushing happens far less often than committing, so a five second wait there is acceptable in a way that the same wait on every commit is not.

Define those as real npm scripts rather than inlining the commands, so the hook and CI call exactly the same thing. If you are not already treating package.json scripts as a shared interface, the npm scripts guide covers the patterns worth adopting.

Git hooks are a property of the repository, not of a package. There is exactly one .git directory, so there is exactly one Husky installation, and it belongs at the workspace root. Installing Husky inside apps/web and expecting it to work is the single most common monorepo mistake.

That creates a wrinkle when the repository root is not the same directory as the Next.js app. Husky handles it with a path argument on the prepare script.

For the linting side, lint-staged resolves the nearest config file to each staged file. That means each workspace package can own its own rules, and a commit touching both apps/web and packages/ui runs each package's tasks against only its own files. You do not need to script the routing yourself.

Keep the root config minimal and let packages specialise. A root lint-staged.config.mjs is still useful as a fallback for files that live outside any package, such as CI workflow files, the root README, and shared tooling config.

A pre-commit hook is a convenience, not a guarantee. Anyone can bypass it, and a pull request opened from the GitHub web UI never runs it at all. CI is where the checks become enforceable, so the rules that block a merge have to live there too.

The mistake to avoid is letting Husky run inside CI. During npm ci, the prepare script executes and installs hooks into a checkout that will never make a commit. It is wasted time at best, and on some runners it fails outright because git metadata is shallow or missing.

Note the asymmetry between the two environments. Locally you run prettier --write because you want files fixed in place before they are committed. In CI you run prettier --check, which writes nothing and exits non-zero when a file is misformatted. Running --write in CI would produce a green build on top of changes nobody ever sees.

Setting HUSKY: 0 at the job level covers every step, including any npm ci in a later job stage. If you deploy from the same workflow, that single environment variable is usually all you need. For a fuller walkthrough of the workflow syntax, see the GitHub Actions tutorial.

If a full-repository lint is too slow for your CI budget, scope it to the files the pull request actually touched instead of falling back to lint-staged. A diff against the merge base gives you the same speed benefit with none of the staging-area assumptions.

Silence is the worst failure mode. A hook that errors loudly gets fixed within minutes, but a hook that never runs can go unnoticed for weeks while unformatted code accumulates. Verify installation directly rather than trusting that it worked.

Start with the one command that tells you whether Git even knows about Husky. On a correct v9 setup it prints .husky/_ and nothing else.

If the first command prints nothing, Husky was never installed in this clone. If it prints .git/hooks, something overwrote the setting, often an older tooling migration or a git config line in an onboarding script. Run npm run prepare and check again.

The empty commit in the third line is the fastest end-to-end test available. It exercises the real hook path without needing a file to stage, and you can drop it afterwards with git reset --hard HEAD~1.

The Git GUI case deserves elaboration because it is genuinely confusing: the setup works perfectly from your terminal and does nothing from Tower, GitHub Desktop, or the VS Code source control panel. Those applications inherit a minimal environment that never sources your shell profile, so nvm, fnm, and volta shims are missing and the hook cannot find node.

Husky v9 sources ~/.config/husky/init.sh before every hook specifically to solve this. Put your version manager setup there once and every hook, in every repository, gets a working PATH.

--no-verify has a bad reputation it only partly deserves. There are situations where skipping the hook is the correct engineering decision, and pretending otherwise just teaches people to alias it permanently.

The legitimate cases share a shape: the hook is checking something that is not relevant to the commit you are making right now.

Two habits keep this honest. First, treat every bypassed commit as debt that gets paid before the pull request opens, not after review starts. Second, make CI the actual gate, so a bypassed hook costs you a red build rather than shipping bad code.

It is also worth separating concerns here. If you have a commit-msg hook validating Conventional Commits, --no-verify skips that too, which is how malformed messages end up in a release changelog. You can check a message against the spec independently with the commit message checker before you push.

Work through this on a fresh clone, not on the machine where you set everything up. A setup that only works for its author is the failure this whole toolchain exists to prevent.

Husky v9, Prettier, and lint-staged take about five minutes to set up and save hours of back-and-forth over formatting in code review.

Keep the pre-commit hook fast: format and lint only staged files. Move tsc --noEmit to a pre-push hook where a slower check is acceptable.