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:

1. Lint check: Run

   npm run lint

   to verify ESLint configuration
2. Format check: Run

   npm run format:check

   to verify Prettier configuration
3. Pre-commit hook: Make a change and commit to test Husky and lint-staged
4. 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