eslint-prettier-husky-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ESLint, Prettier, Husky Configuration

ESLint、Prettier、Husky 配置

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.

为Next.js/React项目配置全套代码质量工具，包括ESLint v9（扁平配置）、Prettier、Husky Git钩子、lint-staged，以及CI代码检查。

Installation and Configuration Steps

安装与配置步骤

1. Install Dependencies

1. 安装依赖包

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

bash

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:

bash

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

安装ESLint v9、Prettier和Git钩子所需的包：

bash

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

对于TypeScript项目，额外安装：

bash

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

2. Create ESLint Flat Config

2. 创建ESLint扁平配置文件

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

在项目根目录创建

eslint.config.mjs

，使用

assets/eslint.config.mjs

中的模板。该扁平配置格式：

采用现代化ESLint v9配置
包含React、React Hooks和JSX可访问性规则
支持带类型检查的TypeScript
忽略Next.js构建目录和配置文件

根据项目需求自定义配置：

调整
```
languageOptions.parserOptions
```
以适配不同ECMAScript版本
修改
```
rules
```
以匹配团队偏好
根据需要添加额外插件

3. Create Prettier Configuration

3. 创建Prettier配置

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

在项目根目录创建

.prettierrc

，使用

assets/.prettierrc

中的模板。该配置：

设置2空格缩进
字符串使用单引号
移除尾随逗号
设置100字符行宽
使用Unix换行符

根据团队风格指南调整格式化规则。

使用

assets/.prettierignore

创建

.prettierignore

文件，排除以下内容：

构建目录（.next、dist、out）
依赖包（node_modules、package-lock.json）
生成文件
公共资源

4. Set Up Husky and Lint-Staged

4. 配置Husky与lint-staged

Initialize Husky for git hooks:

bash

npx husky init

This creates

.husky/

directory with a

pre-commit

hook.

Replace the pre-commit hook content with:

bash

npx lint-staged

Add lint-staged configuration to

package.json

using the example from

references/package-json-config.md

json

{
  "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.

初始化Husky以使用Git钩子：

bash

npx husky init

此命令会创建

.husky/

目录，并生成

pre-commit

钩子。

将pre-commit钩子内容替换为：

bash

npx lint-staged

在

package.json

中添加lint-staged配置，可参考

references/package-json-config.md

中的示例：

json

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

此配置会在每次提交前对暂存文件运行ESLint和Prettier。

5. Add Package Scripts

5. 添加包脚本

Add the following scripts to

package.json

(see

references/package-json-config.md

for complete example):

json

{
  "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

在

package.json

中添加以下脚本（完整示例见

references/package-json-config.md

）：

json

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

这些脚本的作用：

```
npm run lint
```
- 检查代码错误（存在警告则执行失败）
```
npm run lint:fix
```
- 自动修复代码检查问题
```
npm run format
```
- 使用Prettier格式化所有文件
```
npm run format:check
```
- 检查文件格式但不修改
```
prepare
```
- 安装依赖包时自动配置Husky

6. Create GitHub Actions Lint Workflow

6. 创建GitHub Actions Lint工作流

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

使用

assets/github-workflows-lint.yml

中的模板创建

.github/workflows/lint.yml

。该工作流：

在拉取请求和推送到main/master分支时运行
拉取代码并设置Node.js环境
安装依赖包
运行代码检查和格式检查
若存在问题则CI执行失败

自定义工作流：

根据需要调整Node.js版本
修改分支名称以匹配仓库设置
添加缓存以加速CI运行

7. Verify Setup

7. 验证配置

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

测试完整配置：

代码检查：运行
```
npm run lint
```
验证ESLint配置
格式检查：运行
```
npm run format:check
```
验证Prettier配置
提交前钩子：修改代码并提交，测试Husky和lint-staged
CI工作流：推送到分支并打开拉取请求，验证GitHub Actions

修复配置问题：

查看ESLint错误，必要时调整规则
格式化所有文件：
```
npm run format
```
提交配置变更

8. Team Documentation

8. 团队文档

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

为团队成员编写配置文档（模板见

references/team-documentation.md

）：

说明每个工具的用途
为新开发者提供设置指南
记录紧急情况下临时绕过钩子的方法
包含常见问题的排查步骤

Configuration Customization

配置自定义

ESLint Rules

ESLint规则

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

在

eslint.config.mjs

中调整规则的严重程度：

```
"off"
```
- 禁用规则
```
"warn"
```
- 警告（不导致CI失败）
```
"error"
```
- 错误（导致CI失败）

常见自定义项：

禁用特定规则：
```
'react/prop-types': 'off'
```
调整规则选项：
```
'max-len': ['error', { code: 120 }]
```
添加项目特定规则

Prettier Options

Prettier选项

Modify formatting in

.prettierrc

```
printWidth
```
- Line length limit
```
tabWidth
```
- Spaces per indentation level
```
semi
```
- Semicolon preference
```
singleQuote
```
- Quote style
```
trailingComma
```
- Trailing comma rules

在

.prettierrc

中修改格式化设置：

```
printWidth
```
- 行宽限制
```
tabWidth
```
- 缩进空格数
```
semi
```
- 分号偏好
```
singleQuote
```
- 引号风格
```
trailingComma
```
- 尾随逗号规则

Lint-Staged Configuration

lint-staged配置

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:

json

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

在

package.json

中自定义提交前检查：

添加文件类型匹配模式
包含额外命令（测试、类型检查）
调整触发检查的文件与对应工具

带类型检查的示例：

json

{
  "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.

现有代码出现ESLint错误：运行

npm run lint:fix

，再执行

npm run format

以自动修复大部分问题。

Husky钩子未运行：确保初始化Husky后执行了

npm install

。检查

.husky/pre-commit

文件是否可执行。

本地通过但CI失败：验证本地与CI环境的Node.js版本是否一致。检查所有依赖包是否已添加到

package.json

。

ESLint与Prettier冲突：确保

eslint-config-prettier

在extends数组的最后一位，以禁用冲突的ESLint格式化规则。

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

```
package-json-config.md
```
- 包含所有脚本和lint-staged配置的完整package.json示例
```
team-documentation.md
```
- 为团队成员编写配置文档的模板

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

```
eslint.config.mjs
```
- 支持React、TypeScript和Next.js的ESLint v9扁平配置模板
```
.prettierrc
```
- 推荐的Prettier配置
```
.prettierignore
```
- 需排除格式化的文件和目录
```
github-workflows-lint.yml
```
- 用于自动代码检查的GitHub Actions工作流模板