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