告别代码混乱：documenso的ESLint与Prettier自动化配置方案
项目地址: https://gitcode.com/GitHub_Trending/do/documenso 你是否还在为团队代码风格不统一而头疼？是否经常在Code Review时陷入格式之争？documenso通过精心设计的ESLint与Prettier配置，实现了代码质量的自动化保障，让开发者专注于逻辑实现而非格式调整。本文将带你深入了解这套配置方案的实现细节与最佳实践。
项目代码质量配置概览
documenso采用monorepo架构，将代码质量工具配置集中管理在独立包中，确保各子项目使用统一标准。核心配置文件位于：
- ESLint配置包：packages/eslint-config/
- Prettier配置包：packages/prettier-config/
- 提交前校验配置：lint-staged.config.cjs
这种模块化设计使得配置可以在整个项目中共享，同时便于维护和版本控制。
ESLint配置深度解析
ESLint配置文件packages/eslint-config/index.cjs定义了代码检查规则，确保代码质量和一致性。关键配置包括：
核心规则集
配置继承了多个规则集，形成基础检查能力：
extends: ['next', 'turbo', 'eslint:recommended', 'plugin:@typescript-eslint/recommended']
安全相关规则
特别强化了Promise相关的安全检查，防止异步代码错误：
// Safety with promises so we aren't running with scissors
'no-promise-executor-return': 'error',
'prefer-promise-reject-errors': 'error',
'require-atomic-updates': 'error',
'@typescript-eslint/no-floating-promises': 'error',
未使用代码检查
通过unused-imports插件自动检测未使用的导入和变量：
'unused-imports/no-unused-imports': 'warn',
'unused-imports/no-unused-vars': [
'warn',
{
vars: 'all',
varsIgnorePattern: '^_',
args: 'after-used',
argsIgnorePattern: '^_',
destructuredArrayIgnorePattern: '^_',
},
]
Prettier代码格式化配置
Prettier配置文件packages/prettier-config/index.cjs负责代码的格式化规则，确保代码风格统一。
基础格式化规则
定义了代码的基本格式要求：
arrowParens: 'always',
printWidth: 100,
semi: true,
singleQuote: true,
tabWidth: 2,
trailingComma: 'all',
导入排序配置
使用@trivago/prettier-plugin-sort-imports插件实现导入语句的自动排序：
importOrder: [
'^server-only|client-only$',
'^react$',
'^next(/.*)?$',
'<THIRD_PARTY_MODULES>',
'^@documenso/(.*)$',
'^~/(.*)$',
'^[./]',
],
importOrderSeparation: true,
importOrderSortSpecifiers: true,
这种排序规则使得代码结构清晰，依赖关系一目了然。
插件扩展
集成了多个插件增强格式化能力：
plugins: [
'@trivago/prettier-plugin-sort-imports',
'prettier-plugin-tailwindcss',
]
提交前自动化校验流程
通过lint-staged.config.cjs配置，实现提交前的自动化代码检查和格式化：
module.exports = {
'**/*.{ts,tsx,cts,mts}': [eslint, prettier],
'**/*.{js,jsx,cjs,mjs}': [prettier],
'**/*.{yml,mdx}': [prettier],
'**/*/package.json': 'npm run precommit',
};
这个配置确保了：
- TypeScript/TSX文件会经过ESLint修复和Prettier格式化
- JavaScript文件仅需Prettier格式化
- YAML和MDX文件也会被格式化
- package.json文件会触发precommit脚本
多场景格式化示例
TypeScript代码格式化
格式化前：
import {useState} from 'react'
import {Button} from '@documenso/ui/components'
import { formatDate } from '../utils/date'
const MyComponent = () => {
const [count,setCount]=useState(0);
return <Button onClick={()=>setCount(count+1)}>Click me</Button>
}
格式化后：
import { useState } from 'react';
import { Button } from '@documenso/ui/components';
import { formatDate } from '../utils/date';
const MyComponent = () => {
const [count, setCount] = useState(0);
return <Button onClick={() => setCount(count + 1)}>Click me</Button>;
};
SQL文件格式化
Prettier配置中特别针对SQL文件进行了优化：
overrides: [
{
files: ['*.sql'],
options: {
language: 'postgresql',
keywordCase: 'upper',
expressionWidth: 60,
},
},
]
配置应用与扩展
在新项目中集成
要在新项目中使用这些配置，只需安装相应的包：
npm install @documenso/eslint-config @documenso/prettier-config --save-dev
然后在.eslintrc.js和.prettierrc.js中引用：
// .eslintrc.js
module.exports = {
extends: '@documenso/eslint-config',
};
// .prettierrc.js
module.exports = require('@documenso/prettier-config');
自定义规则
如果需要项目特定的规则调整，可以在本地配置文件中覆盖：
// 本地.eslintrc.js
module.exports = {
extends: '@documenso/eslint-config',
rules: {
// 项目特定规则
'no-console': 'warn',
},
};
常见问题与解决方案
规则冲突
ESLint和Prettier可能存在规则冲突，解决方案是使用eslint-config-prettier：
// 在eslint-config/index.cjs中
extends: [
// ...其他规则
'prettier', // 放在最后，禁用ESLint中与Prettier冲突的规则
]
性能优化
对于大型项目，可以通过以下方式优化ESLint性能：
- 使用
--cache选项缓存检查结果 - 合理配置
.eslintignore文件 - 拆分配置为基础和扩展部分
总结与最佳实践
documenso的代码质量保障方案通过以下关键点确保了代码质量：
- 集中化配置管理 - 将ESLint和Prettier配置作为独立包维护
- 自动化流程 - 通过lint-staged在提交前自动执行检查
- 分层规则设计 - 基础规则+项目特定规则的组合方式
- 多语言支持 - 不仅支持JavaScript/TypeScript，还包括SQL等特殊文件
通过这套配置，documenso团队成功减少了90%的代码格式相关讨论，将更多精力投入到功能开发中。建议其他团队根据自身需求，参考此方案构建适合自己的代码质量保障体系。
要了解更多细节，可以查阅项目中的相关配置文件：
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
