ToolJet 贡献者指南ESLint 代码质量检查、编辑器配置与排错实战【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet本篇指南面向 ToolJet 仓库后端server与前端frontend两大工作区的贡献者与日常开发者围绕仓库中的 ESLint 排错文档 展开先讲清 ESLint 在 ToolJet 仓库中扮演的角色与当前使用的 ESLint 9 扁平配置flat config结构再给出从编辑器集成、依赖安装、命令行 lint/format 到常见问题排查的完整可复现流程。读完你可以独立完成 ToolJet 前后端代码的静态检查与一键格式化并能在 CI 与提交钩子之外手动定位和修复 ESLint 报错。ESLint 在 ToolJet 中的作用ToolJet 是一个前后端分离的低代码应用构建平台仓库采用 npm 工作区形态组织核心业务代码集中在 serverNestJS TypeScript与 frontendReact JSX/TSX两个目录中。由于两端的语言风格、框架约束与测试工具差异很大它们各自拥有一套独立的 ESLint 配置与 npm script。正如原文档所述ESLint 作为代码质量工具一方面负责“发现错误并帮助修复”如未使用变量、重复的 jest 测试标题、危险的 TS 语法另一方面强制统一的代码风格配合 Prettier。在 ToolJet 这样体量庞大、多人协作的仓库中一致的 lint 规则是保障代码可读性与降低 review 成本的基础。从源码结构可以确认当前仓库的 ESLint 布局根目录 eslint.config.mjs 本身不做规则声明而是通过动态import直接复用 frontend/eslint.config.mjs让插件解析从frontend/node_modules生效frontend/eslint.config.mjs 使用 ESLint 9 的扁平配置格式分*.js/jsx与*.ts/tsx两个配置块并引入 React、React Hooks、import、Jest、Prettier、Storybook 插件server/eslint.config.js 使用 CommonJS defineConfig通过FlatCompat兼容eslint:recommended、plugin:typescript-eslint/recommended、plugin:prettier/recommended三套推荐规则仓库其余子包cli、plugins、marketplace仍保留旧的.eslintrc.js/.eslintrc与较旧的 ESLint 版本不属于本文“setup / format”命令覆盖的范围。因此下面所有npm run命令都限定在server与frontend两个目录内执行。环境要求原文档给出的最低环境要求为工具要求版本Node.js18.18.2npm9.8.1需要补充说明的是这是项目文档记载的基线版本而当前仓库根目录 package.json 的engines字段实际声明为node: 22.15.1、npm: 10.9.2。仓库内 ESLint 已升级到 9.x见 frontend/package.json 与 server/package.json 的 devDependencies这类新版本对运行时也有更严格要求。建议贡献者使用nvm之类的版本管理器切换到仓库engines声明的版本后再执行安装与检查若本地 Node 低于 18.18ESLint 9 将无法正常启动。可以用以下命令确认当前环境node --version npm --version编辑器集成与默认格式化器设置为了让 ESLint 的错误提示直接显示在编辑器里并在保存时自动修复需要两步基础配置。第一步安装 ESLint 扩展。前往编辑器扩展市场安装官方 ESLint 集成插件VSCode 中为 “ESLint” 扩展。它会在打开文件时读取项目根目录及就近目录的eslint.config.mjs/eslint.config.js并在编辑器底部状态栏提示当前生效的配置。第二步把编辑器的默认格式化器设为 ESLint。只有把默认 formatter 指定为 ESLintFormat Document保存/快捷键触发才会调用 ESLint 的--fix能力而不是被 Prettier 等其他 formatter 抢占。VSCode 用户可在设置里搜索 “Default Formatter” 并选择ESLint或直接写入 settings.json通过Ctrl/Cmd Shift P输入Preferences: Open User Settings (JSON)打开{ // ... editor.defaultFormatter: dbaeumer.vscode-eslint, editor.formatOnSave: true }关键的排错提示原文档重点如果 ESLint 在编辑器中没有生效或规则表现与命令行不一致请检查 VSCodesettings.json中是否存在对 eslint 配置规则的人为覆盖。原文档明确建议注释或删除eslint.options: { ... }这一项。一旦用户在全局 settings 中手写了eslint.options例如自定义了configFile、rulePaths或extensionsVSCode 的 ESLint 扩展就会绕过项目自身的配置文件加载逻辑导致大量“本地命令行能过、编辑器里却报错”的假阳性。排查步骤按Ctrl/Cmd P输入Settings (JSON)在 JSON 中搜索eslint.options若存在则将其注释掉并重启 ESLint 服务命令面板执行ESLint: Restart ESLint Server。安装依赖ToolJet 的server与frontend各自拥有独立的node_modules且 lint 相关的插件如typescript-eslint/*、eslint-plugin-react、eslint-plugin-prettier、globals、babel/eslint-parser都声明在各子包的 devDependencies 中因此必须分别安装。原文档给出的命令如下仓库根目录执行npm install npm install --prefix server npm install --prefix frontend逐条解释npm install安装根目录 package.json 依赖其中包含husky与lint-staged用于 Git 提交钩子npm install --prefix server为后端工作区安装依赖确保server/eslint.config.js引用的typescript-eslint/parser、eslint-plugin-jest等可用npm install --prefix frontend为前端工作区安装依赖。前端配置文件还依赖 Webpack resolver 与 Babel 解析器见下文依赖缺失会导致import/no-unresolved与解析类规则大面积误报。安装完成后建议先用一条最小命令验证 ESLint 可执行npx --prefix server eslint --version npx --prefix frontend eslint --version两个目录应均输出 ESLint 9.x。运行静态检查lint依赖就绪后即可运行检查。原文档给出的命令为npm run --prefix server lint npm run --prefix frontend lint对应到 package.json实际执行的是server/package.jsoneslint . **/*.ts即对server目录下全部文件含**/*.ts模式执行 ESLintfrontend/package.jsoneslint --no-error-on-unmatched-pattern src/**/*.{js,jsx,ts,tsx} ee/**/*.{js,jsx,ts,tsx}即只检查业务源码src与企业版目录ee中的 JS/JSX/TS/TSX 文件。值得注意的前端细节--no-error-on-unmatched-pattern当某个 glob 没有匹配到任何文件时例如开源版检出时不存在ee/目录ESLint 默认会报错退出该选项把这种情况降级为可忽略保证 CE 版也能正常运行 lintfrontend 还额外提供了lint-quiet脚本eslint --quiet ...它只报告error级别的问题而忽略warning适合在改动量大、warn 噪声多时快速收敛到“必须修复的错误”前端配置中的 ignore 清单在 frontend/eslint.config.mjs 顶部声明build/**、assets/**、cypress-tests/**一律跳过检查后端配置在 server/eslint.config.js 尾部通过globalIgnores([**/dist, **/migrations])跳过构建产物与数据库迁移文件——迁移文件为自动化生成且规则诉求不同因此不参与 lint。执行后命令行会按文件汇总error/warning数量。其中 error 通常是必须处理的warning 多数为no-unused-vars变量以_开头可豁免与typescript-eslint/no-explicit-any等提醒项。自动修复与格式化formatlint 发现的问题中很大一部分缩进、引号、分号、未使用导入等可以通过--fix自动修复。原文档给出的格式化命令为npm run --prefix server format npm run --prefix frontend format两条命令等价于对应 lint 命令加上--fixserver/package.jsoneslint . --fix **/*.tsfrontend/package.jsoneslint --fix --no-error-on-unmatched-pattern src/**/*.{js,jsx,ts,tsx} ee/**/*.{js,jsx,ts,tsx}--fix只处理 ESLint 标记为可安全自动修复fixable的规则问题语义层面的错误如jest/no-focused-tests、typescript-eslint/ban-ts-comment仍需要手工处理。关于格式化仓库的机制是Prettier 以 ESLint 插件形态工作而不是独立命令根目录 .prettierrc 是风格规则的“唯一事实来源”声明了printWidth: 120、singleQuote: true、semi: true、trailingComma: es5server/eslint.config.js 与 frontend/eslint.config.mjs 都通过eslint-plugin-prettier将 Prettier 规则桥接进 ESLint并显式把prettier/prettier设为error——这意味着不符合 .prettierrc 风格的代码会以 ESLint error 的形式出现并被format一键修复。前端 TS 配置块还以对象形式内联了一份与 .prettierrc 一致的选项作为兜底。因此贡献者日常只需记住一句话npm run --prefix server|frontend format同时承担了 ESLint 自动修复与 Prettier 排版两种职责。配置文件深度解读为了让贡献者理解“检查到底依据什么”这里补充两端配置的核心构成均以当前仓库文件为准。前端frontend/eslint.config.mjsfrontend/eslint.config.mjs 是 ESLint 9 原生扁平配置结构如下JS/JSX 块**/*.js、**/*.jsx使用babel/eslint-parser并显式指向 frontend/babel.config.js启用 React 相关语法。之所以需要 Babel parser是因为 ToolJet 前端大量使用 JSX 与 Flow 之外的现代 Babel 特性TS/TSX 块**/*.ts、**/*.tsx切换为typescript-eslint/parser启用基于project: tsconfig.json的类型感知解析并应用typescript-eslint的 recommended 规则族包括ban-ts-commenterror、no-non-null-assertionwarn等通用插件eslint-plugin-reactrecommended、eslint-plugin-react-hooksrecommended、eslint-plugin-jest、eslint-plugin-prettier、eslint-plugin-storybook通过flat/recommended平铺到文件尾部import 插件的一个巧妙细节仓库用eslint-plugin-import-x但通过remapImportRules()把规则前缀从import-x/改写回import/并注册在import命名空间下这样源码中既有的eslint-disable import/...注释无需改动即可继续生效项目级覆盖如react/prop-types关闭、no-unused-vars降为 warn 且忽略_前缀、jest/no-disabled-tests为 warn 而jest/no-focused-tests为 error另外配置块将reportUnusedDisableDirectives显式设为off注释说明这是为了防止--fix误删仓库中遗留但插件已不再报错的eslint-disable注释ESLint 9 默认该行为为 warn若开启则--fix会清理这些注释。后端server/eslint.config.jsserver/eslint.config.js 采用 CommonJS 写法兼容 NestJS 传统构建链通过FlatCompat以extends方式继承eslint:recommended、plugin:typescript-eslint/recommended、plugin:prettier/recommendedparserOptions 绑定 server/tsconfig.json开启类型信息project关键覆盖typescript-eslint/no-unused-vars为 errorargs 不检查、no-explicit-any关闭、explicit-function-return-type与explicit-module-boundary-types关闭与 NestJS 代码风格保持一致同时开启no-unsafe-function-type、no-wrapper-object-types、no-empty-object-type三个新规则声明**/dist、**/migrations为全局忽略。后端仓库为 NestJS 风格依赖注入 装饰器TypeScript 语法较为规整因此规则比前端更强调类型安全前端以组件代码为主风格一致性Prettier React Hooks 规则权重更高。这也是两端 lint 命令必须分开执行、分开看结果的原因。根级集成lint-staged 与 husky除手动执行外仓库还在 Git 提交阶段自动 lint。根目录 package.json 声明了lint-stagedlint-staged: { frontend/src/**/*.{js,jsx,ts,tsx}: [ eslint --fix --config frontend/eslint.config.mjs ], server/**/*.ts: [ eslint --fix --config server/eslint.config.js ] }配合prepare: husky install的 Git 钩子每次git commit只会对暂存区中实际改动的文件执行对应的 ESLint--fix。也就是说即便开发时跳过了手动 format提交阶段也会被自动修正若剩余不可自动修复的错误commit 会被阻断此时回到上文lint命令定位并手工处理即可。常见问题排查清单结合原文档与仓库配置按经验将 ESLint 相关故障归纳如下症状可能原因处理方法编辑器内不报错/规则与 CLI 不一致VSCodesettings.json中存在eslint.options覆盖注释掉eslint.options重启 ESLint ServerESLint 命令直接崩溃或提示版本不支持Node 版本过低按仓库根 package.jsonenginesNode 22.15.1切换到受支持的版本前端报大量解析错误Parsing errorfrontend/node_modules未安装或修改过 frontend/babel.config.js执行npm install --prefix frontend确认配置指向正确import/no-unresolved误报resolver 找不到 Webpack alias/、tooljet/plugins等确认使用仓库自带 frontend/webpack.config.js无需修改alias 已在配置的ignore列表中豁免typescript-eslint类型相关规则报错TS 项目文件路径问题检查是否在错误目录执行命令后端必须从server/上下文运行npm run --prefix server lint前端 CE 检出后 lint 命令失败ee/目录不存在导致 glob 无匹配该问题已被--no-error-on-unmatched-pattern覆盖无需处理如手工执行请带上此参数format修不完、仍有排版 error规则属于不可自动修复类型或手动内联了与 .prettierrc 冲突的格式化运行npm run --prefix frontend lint-quiet只看 error排版问题按 .prettierrc120 列、单引号、分号、es5 trailing comma手动调整提交被 lint-staged 阻断暂存文件中存在不可自动修复的 error阅读报错文件与规则名手工修复后重新git add其中“编辑器与 CLI 不一致”是最常见也最隐蔽的问题务必优先检查是否残留eslint.options覆盖项。推荐工作流小结对 ToolJet 贡献者一套稳妥的日常流程是确认 Node/npm 满足仓库 package.json 的engines声明依次执行npm install、npm install --prefix server、npm install --prefix frontend代码提交前运行npm run --prefix server lint与npm run --prefix frontend lint先读清 error运行npm run --prefix server format与npm run --prefix frontend format自动修复可修复项并统一排版再次 lint 确认归零再交给 lint-staged 的提交钩子兜底。在编辑器侧安装官方 ESLint 扩展、将默认格式化器设为 ESLint、清除eslint.options覆盖即可在编写阶段获得与命令行一致的实时反馈——这正是原文档 Setup 部分想要达成的最终状态。如需进一步了解仓库中其他子包的代码风格入口可参考 cli/.eslintrc.js、plugins/.eslintrc.js 与 marketplace/.eslintrc它们与server/frontend的 ESLint 9 配置属于两套体系各自独立运行。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考