ESLint, Prettier, Husky Configuration

Overview

Configure comprehensive code quality tooling for Next.js/React projects using ESLint v9 (flat config), Prettier, Husky git hooks, lint-staged, and CI lint checks.

Installation and Configuration Steps

1. Install Dependencies

Install required packages for ESLint v9, Prettier, and git hooks:

npm install -D eslint@^9 @eslint/js eslint-config-prettier eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y prettier husky lint-staged

For TypeScript projects, add:

npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin typescript-eslint

2. Create ESLint Flat Config

Create eslint.config.mjs in project root using the provided template from assets/eslint.config.mjs . This flat config format:

• Uses modern ESLint v9 configuration

• Includes React, React Hooks, and JSX accessibility rules

• Supports TypeScript with type-aware linting

• Ignores Next.js build directories and configuration files

Customize the configuration based on project needs:

• Adjust languageOptions.parserOptions for different ECMAScript versions

• Modify rules to match team preferences

• Add additional plugins as needed

3. Create Prettier Configuration

Create .prettierrc in project root using the template from assets/.prettierrc . This configuration:

• Sets 2-space indentation

• Uses single quotes for strings

• Removes trailing commas

• Sets 100-character line width

• Uses Unix line endings

Adjust formatting rules to match team style guide.

Create .prettierignore using assets/.prettierignore to exclude:

• Build directories (.next, dist, out)

• Dependencies (node_modules, package-lock.json)

• Generated files

• Public assets

4. Set Up Husky and Lint-Staged

Initialize Husky for git hooks:

npx husky init

This creates .husky/ directory with a pre-commit hook.

Replace the pre-commit hook content with:

npx lint-staged

Add lint-staged configuration to package.json using the example from references/package-json-config.md :

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

This runs ESLint and Prettier on staged files before each commit.

5. Add Package Scripts

Add the following scripts to package.json (see references/package-json-config.md for complete example):

{ "scripts": { "lint": "eslint . --max-warnings 0", "lint:fix": "eslint . --fix", "format": "prettier --write .", "format:check": "prettier --check .", "prepare": "husky" } }

These scripts enable:

• npm run lint

• Check for linting errors (fails on warnings)

• npm run lint:fix

• Auto-fix linting issues

• npm run format

• Format all files with Prettier

• npm run format:check

• Check formatting without modifying files

• prepare

• Automatically set up Husky when installing dependencies

6. Create GitHub Actions Lint Workflow

Create .github/workflows/lint.yml using the template from assets/github-workflows-lint.yml . This workflow:

• Runs on pull requests and pushes to main/master

• Checks out code and sets up Node.js

• Installs dependencies

• Runs both linting and format checks

• Fails CI if any issues are found

Customize the workflow:

• Adjust Node.js version as needed

• Modify branch names to match repository

• Add caching for faster CI runs

7. Verify Setup

Test the complete setup:

• Lint check: Run npm run lint to verify ESLint configuration

• Format check: Run npm run format:check to verify Prettier configuration

• Pre-commit hook: Make a change and commit to test Husky and lint-staged

• CI workflow: Push to a branch and open a PR to verify GitHub Actions

Fix any configuration issues:

• Review ESLint errors and adjust rules if needed

• Format all files: npm run format

• Commit the configuration changes

8. Team Documentation

Document the setup for team members (see references/team-documentation.md for template):

• Explain the purpose of each tool

• Provide setup instructions for new developers

• Document how to temporarily bypass hooks (for emergencies only)

• Include troubleshooting steps for common issues

Configuration Customization

ESLint Rules

Adjust rule severity in eslint.config.mjs :

• "off"

• Disable rule

• "warn"

• Warning (doesn't fail CI)

• "error"

• Error (fails CI)

Common customizations:

• Disable specific rules: 'react/prop-types': 'off'

• Adjust rule options: 'max-len': ['error', { code: 120 }]

• Add project-specific rules

Prettier Options

Modify formatting in .prettierrc :

• printWidth

• Line length limit

• tabWidth

• Spaces per indentation level

• semi

• Semicolon preference

• singleQuote

• Quote style

• trailingComma

• Trailing comma rules

Lint-Staged Configuration

Customize pre-commit checks in package.json :

• Add file type patterns

• Include additional commands (tests, type checking)

• Adjust which files trigger which linters

Example with type checking:

{ "lint-staged": { "*.{ts,tsx}": [ "eslint --fix", "prettier --write", "tsc-files --noEmit" ] } }

Troubleshooting

ESLint errors on existing code: Run npm run lint:fix then npm run format to auto-fix most issues.

Husky hooks not running: Ensure npm install was run after Husky initialization. Check .husky/pre-commit is executable.

CI failing but local passes: Verify Node.js version matches between local and CI. Check that all dependencies are in package.json .

Conflicts between ESLint and Prettier: Ensure eslint-config-prettier is last in extends array to disable conflicting ESLint formatting rules.

Resources

scripts/

No executable scripts needed for this skill.

references/

• package-json-config.md

• Complete package.json example with all scripts and lint-staged configuration

• team-documentation.md

• Template for documenting the setup for team members

assets/

• eslint.config.mjs

• ESLint v9 flat config template with React, TypeScript, and Next.js support

• .prettierrc

• Prettier configuration with recommended settings

• .prettierignore

• Files and directories to exclude from formatting

• github-workflows-lint.yml

• GitHub Actions workflow for automated lint checks