Monorepo代码规范：搭建 typeScript+ eslint + prettier + vscode 组件库开发环境

前言

使用 monorepo 整合多个项目，多个项目可能技术栈不一样，代码检测规范也不一样，那么如何共享项目 typescript 和 eslint 等配置就显得很重要。如果每个项目单独分散配置，管理起来就比较繁琐，想到的方案是将 typescript 和 eslint 抽离到单独的包，如 @swc-ui/typescript-config、 @swc-ui/eslint-config，在各个项目继承去使用，接下来介绍如何在项目中搭建。

Typescript 环境搭建

在根目录创建 config 目录，管理项目配置，初始化 typescript 项目

pnpm init

执行后初始化 package.json 文件，分别创建 base.json 和 stencil.json 文件

base.json 是共享的基础配置

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Default",
  "compilerOptions": {
    "target": "ES2022",
    "removeComments": true,
    "strict": true,
    "declaration": true,
    "declarationDir": "types",
    "declarationMap": true,
    "esModuleInterop": true,
    "incremental": false,
    "isolatedModules": true,
    "lib": ["es2022", "DOM", "DOM.Iterable"],
    "module": "NodeNext",
    "moduleDetection": "force",
    "moduleResolution": "NodeNext",
    "noUncheckedIndexedAccess": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
  }
}

stencil.json 继承 base.json，其中比较重要的要开启 experimentalDecorators 和 jsx 配置，因为 stencil 开发组件要使用 jsx 语法 和 装饰器

{
  // 继承配置
  "extends": "./base.json",
  "compilerOptions": {
    "declaration": false,
    // 开启装饰器
    "experimentalDecorators": true,
    "module": "ESNext",
    "moduleResolution": "node",
    "allowJs": true,
    "jsx": "react",
    "jsxFactory": "h",
    "noEmit": true
  }
}

修改 package.json name 包名为 @swc-ui/typescript-config，添加 files 发布包会用到

// config/typescript/package.json
{
  "name": "@swc-ui/typescript-config",
  "files": [
    "base.json",
    "stencil.json"
  ],
  "publishConfig": {
    "access": "public"
  }
}

将 @swc-ui/typescript-config 安装到跟目录下

pnpm add @swc-ui/typescript-config -D -w

在根目录 package.json 新增如下

{
  //...
  "devDependencies": {
    //...
    "@swc-ui/typescript-config": "workspace:^",
  }
}

最后在 components 包 packages/components/tsconfig.json 引入使用

{
  "extends": "@swc-ui/typescript-config/stencil.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "loader", ".stencil", ".turbo"]
}

至此，monorepo 项目 typescript 环境搭建完成。

如果是要安装 vue 项目 typescript，可以在 config/typescript 包下创建 vue.json 配置文件，使用 @swc-ui/typescript-config/vue.json 引入，这样管理 typescript 配置就显得方便些

同理，搭建 eslint 包过程相似，安装后目录结构

ESlint

eslint 可以封装自己的共享配置，发布到 npm 供多个项目使用，具体介绍共享配置，主要使用 extends 继承，接下来搭建 @swc-ui/eslint-config 共享配置

在 config/eslint 安装 typescript 相关依赖

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

eslint 安装到根目录 pnpm add eslint -D -w

在 config/eslint 目录新建 base.js 设置基础规则

module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  env: {
    browser: true,
    node: true,
    es6: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/eslint-recommended',
    'plugin:@typescript-eslint/recommended'
  ],
  // add your custom rules here
  rules: {
    // 如果有console，会抛出错误
    'no-console': 2,
    // 在对象中使用getter/setter
    'accessor-pairs': 2,
    // =>的前/后括号
    'arrow-spacing': [
      2,
      {
        before: true,
        after: true,
      },
    ],
    // 在循环内禁止`await`
    'block-spacing': [2, 'always'],
    // if while function 后面的{必须与if在同一行，java风格
    'brace-style': [
      2,
      '1tbs',
      {
        allowSingleLine: true,
      },
    ],
    // 强制驼峰法命名
    camelcase: [
      0,
      {
        properties: 'always',
      },
    ],
    // always-multiline：多行模式必须带逗号，单行模式不能带逗号 off->2
    'comma-dangle': ['off', 'never'],
    // 控制逗号前后的空格
    'comma-spacing': [
      2,
      {
        before: false,
        after: true,
      },
    ],
    // 控制逗号在行尾出现还是在行首出现
    'comma-style': [2, 'last'],
    // 强制在子类构造函数中用super()调用父类构造函数，TypeScrip的编译器也会提示
    'constructor-super': 2,
    // 强制所有控制语句使用一致的括号风格
    curly: [2, 'multi-line'],
    // object, '.' 号应与对象名在同一行
    'dot-location': [2, 'property'],
    // 文件末尾强制换行
    'eol-last': 2,
    // 使用 === 替代 ==
    eqeqeq: ['off'],
    // 生成器函数*的前后空格
    'generator-star-spacing': [
      2,
      {
        before: true,
        after: true,
      },
    ],
    // nodejs 处理错误
    'handle-callback-err': [2, '^(err|error)$'],
    // 缩进风格 off->2
    indent: [
      'error',
      2,
      {
        SwitchCase: 1,
      },
    ],
    // JSX 属性中一致使用双引号或单引号
    'jsx-quotes': [2, 'prefer-double'],
    // 对象字面量中冒号的前后空格
    'key-spacing': [
      2,
      {
        beforeColon: false,
        afterColon: true,
      },
    ],
    // 在关键字前后强制使用一致的空格
    'keyword-spacing': [
      2,
      {
        before: true,
        after: true,
      },
    ],
    // 函数名首行大写必须使用new方式调用，首行小写必须用不带new方式调用
    'new-cap': [
      2,
      {
        newIsCap: true,
        capIsNew: false,
      },
    ],
    // 在调用没有参数的构造函数时强制或禁止使用圆括号
    'new-parens': 2,
    // 不允许"数组"构造函数
    'no-array-constructor': 2,
    // 不允许使用"arguments.caller"或"arguments.callee"
    'no-caller': 2,
    // 禁止重新分配类成员
    'no-class-assign': 2,
    // 在条件表达式中禁止赋值操作符
    'no-cond-assign': 2,
    // 禁止对const变量重新赋值
    'no-const-assign': 2,
    // 禁止在正则表达式中使用控制字符
    'no-control-regex': 0,
    // 不允许删除变量 var
    'no-delete-var': 2,
    // 在"函数"定义中禁止重复参数
    'no-dupe-args': 2,
    // 禁止重复的类成员
    'no-dupe-class-members': 2,
    // 禁止在对象字面量中出现重复的键
    'no-dupe-keys': 2,
    // 禁止重复的大小写标签
    'no-duplicate-case': 2,
    // 禁止在正则表达式中使用空字符类
    'no-empty-character-class': 2,
    // 不允许空解构模式
    'no-empty-pattern': 2,
    // 禁止使用' eval()
    'no-eval': 2,
    // 禁止在' catch '子句中重新赋值异常
    'no-ex-assign': 2,
    // 禁止扩展本机类型
    'no-extend-native': 2,
    // 禁止不必要地调用' .bind() '
    'no-extra-bind': 2,
    // 禁止不必要的布尔类型转换
    'no-extra-boolean-cast': 2,
    // 禁止不必要的括号
    'no-extra-parens': [2, 'functions'],
    // 禁止跌落' case '语句
    'no-fallthrough': 2,
    // 在数字字面值中禁止前导或后导小数点
    'no-floating-decimal': 2,
    // 禁止对' function '声明重新赋值
    'no-func-assign': 2,
    // 禁止使用' eval() '类方法
    'no-implied-eval': 2,
    // 禁止在嵌套块中声明变量或'函数'
    'no-inner-declarations': [2, 'functions'],
    // 禁止在' RegExp '构造函数中使用无效的正则表达式字符串
    'no-invalid-regexp': 2,
    // 不允许不规则的空白
    'no-irregular-whitespace': 2,
    // 禁止使用' __iterator__ '属性
    'no-iterator': 2,
    // 禁止与变量共享名称的标签
    'no-label-var': 2,
    // 不允许标记语句
    'no-labels': [
      2,
      {
        allowLoop: false,
        allowSwitch: false,
      },
    ],
    // 禁止不必要的嵌套块
    'no-lone-blocks': 2,
    // 禁止使用空格和制表符混合进行缩进
    'no-mixed-spaces-and-tabs': 2,
    // 不允许多行空格
    'no-multi-spaces': 2,
    // 不允许多行字符串
    'no-multi-str': 2,
    // 禁止多个空行
    'no-multiple-empty-lines': [
      2,
      {
        max: 1,
      },
    ],
    // 禁止赋值给本机对象或只读全局变量+
    'no-global-assign': 2,
    // 禁止对关系操作符的左操作数取反+
    'no-unsafe-negation': 2,
    'no-native-reassign': 2,
    'no-negated-in-lhs': 2,
    // 不允许对象的构造函数
    'no-new-object': 2,
    'no-new-require': 2,
    // 禁止"Symbol"对象使用"new"操作符
    'no-new-symbol': 2,
    // 禁止使用' String '、' Number '和' Boolean '对象的' new '操作符
    'no-new-wrappers': 2,
    // 禁止调用全局对象属性作为函数
    'no-obj-calls': 2,
    // 不允许八进制文字
    'no-octal': 2,
    // 禁止在字符串字面量中使用八进制转义序列
    'no-octal-escape': 2,
    'no-path-concat': 2,
    // 禁止使用' __proto__ '属性
    'no-proto': 2,
    // 不允许变量redeclaration
    'no-redeclare': 2,
    // 禁止在正则表达式中使用多个空格
    'no-regex-spaces': 2,
    // 禁止在' return '语句中使用赋值操作符
    'no-return-assign': [2, 'except-parens'],
    // 禁止两边完全相同的作业
    'no-self-assign': 2,
    // 禁止两边完全相同的比较
    'no-self-compare': 2,
    // 不允许逗号操作符
    'no-sequences': 2,
    // 禁止标识符隐藏受限制的名称
    'no-shadow-restricted-names': 2,
    // 要求或不允许函数标识符与其调用之间有空格+
    'func-call-spacing': 2,
    'no-spaced-func': 2,
    // 不允许稀疏阵列
    'no-sparse-arrays': 2,
    // 在构造函数中调用super()之前禁止使用' this ' / ' super '
    'no-this-before-super': 2,
    // 禁止将文字作为异常抛出
    'no-throw-literal': 2,
    // 禁止行尾有空格
    'no-trailing-spaces': 2,
    // 禁止使用未声明的变量，除非在' /*global */ '注释中提到
    'no-undef': 2,
    // 禁止将变量初始化为"undefined"
    'no-undef-init': 2,
    // 禁止混乱的多行表达式
    'no-unexpected-multiline': 2,
    // 禁止未修改的循环条件
    'no-unmodified-loop-condition': 2,
    // 当存在更简单的选择时，禁止使用三元运算符
    'no-unneeded-ternary': [
      2,
      {
        defaultAssignment: false,
      },
    ],
    // 禁止在' return '， ' throw '， ' continue '和' break '语句之后出现不可到达的代码
    'no-unreachable': 2,
    // 禁止在' finally '块中使用控制流语句
    'no-unsafe-finally': 2,
    // 不允许未使用的变量
    'no-unused-vars': [
      2,
      {
        vars: 'all',
        args: 'none',
      },
    ],
    // 禁止不必要地调用' .call() '和' .apply()
    'no-useless-call': 2,
    // 禁止在对象和类中使用不必要的计算属性键
    'no-useless-computed-key': 2,
    // 禁止不必要的构造函数
    'no-useless-constructor': 2,
    // 禁止不必要的转义字符
    'no-useless-escape': 0,
    // 属性前不允许有空格
    'no-whitespace-before-property': 2,
    // 不允许`with`语句
    'no-with': 2,
    // 强制在函数中同时声明或单独声明变量
    'one-var': [
      2,
      {
        initialized: 'never',
      },
    ],
    // 强制操作符使用一致的换行样式
    'operator-linebreak': [
      2,
      'after',
      {
        overrides: {
          '?': 'before',
          ':': 'before',
        },
      },
    ],
    // 要求或禁止在块内填充
    'padded-blocks': [2, 'never'],
    // 强制一致使用反引号、双引号或单引号
    quotes: [
      2,
      'single',
      {
        avoidEscape: true,
        allowTemplateLiterals: true,
      },
    ],
    // 要求或不允许用分号代替ASI off->2
    semi: ['off', 'never'],
    // 强制分号前后有一致的空格
    'semi-spacing': [
      2,
      {
        before: false,
        after: true,
      },
    ],
    // 强制在块之前有一致的空格
    'space-before-blocks': [2, 'always'],
    // 强制在"函数"定义开括号前有一致的空格
    'space-before-function-paren': [0, 'never'],
    // 在圆括号内强制使用一致的空格
    'space-in-parens': [2, 'never'],
    // 要求中缀操作符周围有空格
    'space-infix-ops': 2,
    // 强制一元运算符前后有一致的空格
    'space-unary-ops': [
      2,
      {
        words: true,
        nonwords: false,
      },
    ],
    // 空格注释强制在注释中的' // '或' /* '后面有一致的空格
    'spaced-comment': [
      2,
      'always',
      {
        markers: ['global', 'globals', 'eslint', 'eslint-disable', '*package', '!', ','],
      },
    ],
    // 要求或禁止模板字符串内嵌表达式周围有空格
    'template-curly-spacing': [2, 'never'],
    // 检查' NaN '时要求调用' isNaN() '
    'use-isnan': 2,
    // 强制将' typeof '表达式与有效字符串进行比较
    'valid-typeof': 2,
    // 要求立即调用' function '时使用圆括号
    'wrap-iife': [2, 'any'],
    // 要求或禁止' yield* '表达式中的' * '周围有空格
    'yield-star-spacing': [2, 'both'],
    // 要求或不允许"尤达"条件
    yoda: [2, 'never'],
    // 对于声明后从未重新赋值的变量，要求使用' const '声明
    'prefer-const': 2,
    // 禁止使用'debugger'
    'no-debugger': process.env.NODE_ENV === 'production' ? 2 : 0,
    // 在大括号内强制使用一致的空格
    'object-curly-spacing': [
      2,
      'always',
      {
        objectsInObjects: true,
      },
    ],
    // 在数组括号内强制使用一致的空格
    'array-bracket-spacing': [2, 'never'],
  },
};

创建 stencil.js 使用 extends 继承 base.js，可以在 stencil.js 定制 components 项目 eslint 规则

module.exports = {
  extends: ['./base.js'],
  // plugins: ['only-warn'],
  globals: {
    React: true,
    JSX: true,
  },
};

在根目录安装 eslint 包配置 pnpm add @swc-ui/eslint-config -D -w

在 components 项目新建 .eslintrc.js 文件，引入 eslint 共享配置

module.exports = {
  root: true,
  extends: ['@swc-ui/eslint-config/stencil'],
};

接下来测试一下，在 config/eslint/base.js 新增一条规则，不允许使用 console

"rules": { 
    "no-console": 2 // 如果有console，会抛出错误
  }

在 src/index.ts 输入 console.log('hello');

进入 packages/components 运行 npx eslint src/index.ts 出现一个报错，说明 eslint 配置生效了

prettier 配置

在 config/eslint 共享配置 eslint，安装依赖

pnpm add prettier eslint-plugin-prettier eslint-config-prettier -D --filter @swc-ui/eslint-config

eslint-config-prettier 用来关闭所有和 prettier 冲突的 eslint 规则（prettier的规则时没有办法关闭的，很霸道！）。eslint-plugin-prettier 告诉 eslint 应该怎么按照 prettier 的方式去格式化文档

修改 config/eslint/base.js，要保证 plugin:prettier/recommended 放在 extends 最后

  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/eslint-recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:prettier/recommended',
  ],

在 components 根目录新建 .prettierrc.js

module.exports = {
  // 一行最多 120 字符
  printWidth: 120,
  // 使用 2 个空格缩进
  tabWidth: 2,
  // 不使用缩进符，而使用空格
  useTabs: false,
  // 行尾需要有分号
  semi: true,
  // 使用单引号
  singleQuote: true,
  // 对象的 key 仅在必要时用引号
  quoteProps: 'as-needed',
  // jsx 不使用单引号，而使用双引号
  jsxSingleQuote: false,
  // 末尾需要有逗号
  trailingComma: 'all',
  // 大括号内的首尾需要空格
  bracketSpacing: true,
  // jsx 标签的反尖括号需要换行
  arrowParens: 'always',
  // 每个文件格式化的范围是文件的全部内容
  rangeStart: 0,
  rangeEnd: Infinity,
  // 不需要写文件开头的 @prettier
  requirePragma: false,
  // 不需要自动在文件开头插入 @prettier
  insertPragma: false,
  // 使用默认的折行标准
  proseWrap: 'preserve',
  // 根据显示样式决定 html 要不要折行
  htmlWhitespaceSensitivity: 'css',
  // 换行符使用 lf
  endOfLine: 'lf',
  // 格式化嵌入的内容
  embeddedLanguageFormatting: 'auto',
};

VSCode 配置

在项目创建 .vscode 目录，配置 settings.json 用于在当前项目设置 VSCode 编辑器

{
  // 设置保存时格式化。只用于用于格式化css/less程序
  "editor.formatOnSave": true,
  // 关闭js/ts的默认format,统一用eslint进行格式化（tslint已经不维护了，所以转eslint吧）
  "javascript.format.enable": false,
  "typescript.format.enable": false,
  // 关闭vetur的js/ts/html的formatter。html用eslint-plugin-vue格式化。
  // js/ts程序用eslint，防止vetur中的prettier与eslint格式化冲突
  "vetur.format.defaultFormatter.html": "none",
  "vetur.format.defaultFormatter.js": "none",
  "vetur.format.defaultFormatter.ts": "none",
  // 开启eslint自动修复js/ts/jsx/tsx功能
  "eslint.format.enable": false,
  // 设置js的formatter为eslint
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[scss]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  // jsonc是有注释的json
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "eslint.enable": true,
  "eslint.codeActionsOnSave.mode": "problems",
  "eslint.validate": ["typescript", "javascript", "javascriptreact", "typescriptreact"],
  // 将json文件识别为jsonc格式
  "files.associations": {
    "*.json": "jsonc"
  },
  "editor.cursorBlinking": "smooth",
  "editor.minimap.enabled": true,
  "editor.minimap.renderCharacters": false
}

项目在保存时自动执行lint操作，帮助我们自动修复

当随便打一个空格，prettier 校验不通过，保存后帮我们格式化自动修复

至此，项目的代码规范搭建完成，至于 Stylelint 还有其他配置优化在开发使用遇到再配置了。

如果能对新技术开发组件库感兴趣，也欢迎加入stencil-component-ui，给个 star 鼓励一下 👏👏