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/ToolJetESLint 是 ToolJet 前端与后端代码库共同的代码质量守门员负责检查语法错误、强制统一编码风格并与 Prettier 协同实现保存即格式化。本文基于 ToolJet 3.0.0-LTS 版本文档完整梳理 ESLint 的本地环境搭建、依赖安装、检查与自动修复命令并深入根仓库的 flat config、lint-staged与.prettierrc源码帮助你理解规则从配置到执行的完整链路快速定位格式化不生效lint 报错不一致等高频问题。ESLint 在 ToolJet 中扮演什么角色ESLint 是一种代码质量工具code quality tool它静态扫描代码找出潜在错误、帮助修复问题并强制统一编码风格。在 ToolJet 这种横跨 frontendReact Redux 大量 JSX/TSX与 serverNestJS TypeScript的大型 monorepo 中ESLint 承担了双重职责错误预防在代码进入 CI 之前拦截未定义变量、重复导入、不合法的 React Hooks 调用等隐患风格统一与 Prettier 联动将格式化规则引号、分号、行宽、尾逗号固化为可机器执行的标准。值得注意的是ToolJet 的 ESLint 配置还内建了Jest 规则如jest/no-focused-tests报 error与Storybook 规则保证测试用例和组件示例代码同样受到约束。环境准备Node 与 npm 版本要求按 3.0.0-LTS 文档要求搭建本地 ESLint 环境需要满足工具版本Node.js18.18.2npm9.8.1Node 18.18.2ToolJet 3.0.0-LTS 的官方支持版本建议通过 nvm 安装npm 9.8.1官方文档特别提示npm 版本不匹配会触发fsevents相关错误。完整的版本安装指引见 贡献环境搭建指南其中明确给出了两条命令nvm install 18.18.2 npm i -g npm9.8.1提示当前仓库根目录 package.json 的engines字段已声明更新的运行时Node 22 / npm 10如果你在开发环境遇到版本冲突请以你正在贡献的版本分支对应的文档要求为准优先保证 Node 18.18.2 npm 9.8.1。第一步配置代码编辑器的 ESLint 集成要让 ESLint 在写代码时实时反馈红色波浪线并在保存时自动修复需要完成编辑器侧的两步配置安装 ESLint 扩展为你的代码编辑器安装官方 ESLint 集成扩展VSCode 对应 ESLint 扩展它负责在编辑器中运行 ESLint 并将诊断信息展示给开发者。将默认格式化器设置为 ESLint在编辑器设置中把默认 Formatter 指定为ESLint从而让保存即格式化format on save走 ESLint 的--fix流程而不是与其他格式化器打架。:::tip VSCode 用户专属提示 通过快捷键Ctrl/Cmd P打开命令面板输入并选择Settings (JSON)直接编辑settings.json。请重点检查是否存在对 ESLint 配置的覆盖特别是eslint.options: {...}字段——它会以传入的选项覆盖仓库自身的规则配置导致 lint 结果与 CI 不一致。建议将eslint.options相关规则注释掉让 ESLint 完全读取仓库的配置文件。 :::第二步安装依赖ToolJet 的 ESLint 插件与规则分散在根目录、server和frontend三个package.json中因此需要分别在三个层级安装依赖npm install npm install --prefix server npm install --prefix frontendnpm install安装根目录依赖其中包含eslint^9.x、lint-staged、husky等见 package.json 的devDependenciesnpm install --prefix server安装后端依赖typescript-eslint/*、eslint-plugin-prettier等npm install --prefix frontend安装前端依赖包括babel/eslint-parser、eslint-plugin-react、eslint-plugin-react-hooks、eslint-plugin-jest、eslint-plugin-storybook、eslint-import-resolver-webpack等见 frontend/package.json。第三步运行 Lint 检查依赖安装完成后分别对后端与前端执行代码检查npm run --prefix server lint npm run --prefix frontend lint这两条命令的底层实现源码可验证server见 server/package.json 中的脚本lint:eslint . **/*.ts对整个 server 目录的 TypeScript 文件执行检查frontend见 frontend/package.json 中的脚本lint:eslint --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 暂无匹配文件时不会直接报错中断。第四步自动修复 ESLint 错误与警告对于可自动修复的问题如格式问题、部分 import 顺序可以直接让 ESLint 执行--fixnpm run --prefix server format npm run --prefix frontend formatserver的formateslint . --fix **/*.ts等价于 lint 自动修复frontend的formateslint --fix --no-error-on-unmatched-pattern src/**/*.{js,jsx,ts,tsx} ee/**/*.{js,jsx,ts,tsx}。补充frontend 还提供了lint-quiet脚本eslint --quiet ...只展示 error 级别的错误忽略 warning适合在大量 warning 干扰时快速定位硬错误。源码级解析ToolJet 的 ESLint 配置体系理解配置文件才能解释为什么 lint 结果是这样。ToolJet 当前使用 ESLint 9 的flat config体系配置文件按模块拆分根目录统一入口根目录 eslint.config.mjs 仅做了一件事——动态导入frontend/eslint.config.mjs并导出const { default: config } await import(./frontend/eslint.config.mjs); export default config;即前端配置是仓库的主配置来源动态导入保证插件从frontend/node_modules解析。frontendJS/JSX 与 TS/TSX 双轨配置frontend/eslint.config.mjs 是整个仓库最完整的配置包含四个配置块全局 ignores忽略build/**、assets/**、cypress-tests/**JS/JSX 块使用babel/eslint-parser绑定 frontend/babel.config.js叠加globals.browser/node/jest等环境启用 react、react-hooks、import、jest、prettier 插件TS/TSX 块使用typescript-eslint/parser基于frontend/tsconfig.json做类型感知检查启用typescript-eslint/recommended规则集并关闭与 TS 冲突的 ESLint 基础规则如no-undef、no-unused-varsStorybook 块继承flat/recommended保证组件示例代码也受控。几个值得注意的项目级规则源码注释直接佐证no-unused-vars设为warn且argsIgnorePattern/varsIgnorePattern为^_即以下划线开头的参数/变量不告警jest/no-focused-tests、jest/no-identical-title、jest/valid-expect为error防止.only等测试反模式进入主干import/no-unresolved为error但对/、tooljet/plugins、react-hot-toast等模块路径做了 ignoreprettier/prettier强制为error其参数在 TS 块中显式写出semi: true, trailingComma: es5, printWidth: 120, singleQuote: true, arrowParens: always——与根目录 .prettierrcprintWidth: 120、singleQuote: true、semi: true、trailingComma: es5保持一致单一事实来源。serverTypeScript 专用配置server/eslint.config.js 通过eslint/eslintrc的FlatCompat兼容经典extends写法继承eslint:recommended、plugin:typescript-eslint/recommended、plugin:prettier/recommended并通过globalIgnores([**/dist, **/migrations])跳过构建产物与迁移文件关闭typescript-eslint/no-explicit-any后端允许显式 anytypescript-eslint/no-unused-vars为errorvars: allargs: none。提交前自动检查lint-staged根目录 package.json 中的lint-staged配置把 ESLint 接入了 Git 提交钩子配合huskylint-staged: { frontend/src/**/*.{js,jsx,ts,tsx}: [eslint --fix --config frontend/eslint.config.mjs], server/**/*.ts: [eslint --fix --config server/eslint.config.js] }这意味着git commit时只会对暂存区内的变更文件执行 lint 自动修复既保证提交质量又不拖慢大型仓库的整体检查速度。常见问题排查1. 编辑器 lint 结果与命令行不一致优先检查 VSCodesettings.json中是否存在eslint.options对规则的覆盖按本文第一步提示注释掉相关字段同时确认编辑器的 ESLint 扩展确实读取的是仓库根配置而不是某个全局配置。此外VSCode 的editor.defaultFormatter应设为ESLint否则保存时可能被其他格式化器改写代码后再次触发 lint 报错。2. 安装依赖时报fsevents相关错误按文档要求将 npm 固定为 9.8.1npm i -g npm9.8.1并确认 Node 版本为 18.18.2此错误通常由 npm 版本与锁文件不兼容引起。3. 运行 lint 提示找不到配置文件或插件ToolJet 的 flat config 依赖frontend/node_modules与server/node_modules中的插件解析。如果只执行了根目录npm install而未执行--prefix server/--prefix frontend安装会导致插件缺失。请完整执行本文第二步的三条安装命令。4. 只想快速修复本次改动可以直接调用根目录的lint-staged机制提交时自动执行或对单个文件手动执行npx eslint --fix --config frontend/eslint.config.mjs frontend/src/你的文件.jsx npx eslint --fix --config server/eslint.config.js server/src/你的文件.ts这样既享受了配置又避免全量检查带来的耗时。总结ToolJet 的 ESLint 体系是一个编辑器实时反馈 命令行全量检查 git 提交前增量修复的三层防线先按 Node 18.18.2 / npm 9.8.1 搭好环境配置编辑器扩展与默认格式化器再依次执行server、frontend的lint与format命令即可完成日常检查与修复。理解 frontend/eslint.config.mjs、server/eslint.config.js 与 .prettierrc 的分工以及 package.json 中lint-staged的提交钩子能让你在遇到编辑器与 CI 结果不一致时迅速定位问题根源——多数情况下问题都出在编辑器对eslint.options的覆盖或依赖未完整安装上。【免费下载链接】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），仅供参考