从零开始配置 react + typescript（二）：linters 和 formatter

继 从零开始配置 react + typescript（一）：dotfiles 介绍了一些最先配置的 dotfiles，本篇将继续介绍 lint 工具 eslint，stylelint，代码格式化工具 prettier，用 husky + lint-staged 来实现每次 commit 时只 lint 修改过的代码，以及使用 commitlint 来规范化 commit message。

eslint

Find and fix problems in your JavaScript code

其实社区有很多的 lint 工具，例如 eslint, stylelint, tslint, htmllint, markdownlint 等。lint 工具一方面可以帮助维护团队成员保持统一良好的代码风格，而且可以定制自己团队的规则集合，另一面可以帮助我们检测出代码的坏味道，降低 bug 的产生的可能性，甚至提高代码的执行效率，提高代码质量。需要指出的是：lint 工具有一定的格式化能力，但是主要功能不是负责格式化代码，格式化代码应该交给专门的格式化工具。 我们这个项目就将准备使用 prettier 进行代码格式化。

因为是打算使用 TypeScript 来编写 react，TypeScript 的 lint 工具有俩，tslint 和 eslint。去年 2019 年 2 月份 tslint 团队就宣布了要废弃 tslint，转而将维护一系列将 TypeScript 集成到 ESLint 的工具。具体可以看这个 issue 和这篇博客：TSLint in 2019。

2020 年我觉得新项目没有任何理由还去选择 tslint，eslint 的 TypeScript 插件已经算是比较成熟了，虽然还是有挺多的 bug，后面会提到一些 bug。

其实前端绝大多数构建工具都是用 node 编写模块来提供 API，有些也会提供命令行工具，本质上就是解析用户输入调用 node API，然后可以通过配置文件来配置选项和集成插件。

eslint 也不例外，配置 eslint 建议使用 eslint 命令行工具提供的交互式配置生成器。很多包既可以全局安装，也可以本地安装，我们选择本地安装，因为你没办法确保别人开发这个项目的时候也全局安装了，而且这样还可以保证都是使用同一版本。

安装 eslint：

# -D 参数表示开发依赖
yarn add eslint -D
复制代码

调用 eslint 自带的配置生成器：

npx eslint --init
复制代码

npx 是 npm 5.2 自带的一个命令，x 就是和文件类型描述符的那个 x 一样表示 execute 执行嘛。如果本地安装了就会用本地的 eslint，没安装就去找全局的，全局再没有就在临时目录下载 eslint，用完就删。用起来比 npm scripts 还方便，传参数不用像 npm scripts 一样要在参数前加 --。执行上面的 eslint 初始化命令后会询问你一系列的问题，关于每一个问题的详细说明建议看一下这篇文章 Setting up ESLINT in your JavaScript Project with VS Code，这篇文章说的很细。

• How would you like to use ESLint?

  我们选择第三条，选择其它几条就不会问我们是否选择 Google，Airbnb 还是 Standard 风格了

• What type of modules does your project use?

  我们选择 JavaScript modules (import/export)，包括 webpack 配置等 node 脚本我们都将使用 ts 来编写，所以选择 esm

• Which framework does your project use?

  显然选择 react

• Does your project use TypeScript?

  这一步一定要选 Y，只有告诉初始化器我们使用 TypeScript，它才会帮助我们配置好 TypeScript 的 ESLint parser，相关的 plugins， 以及其它配置

• Where does your code run?

  这里我们 browser 和 node 两个都选上，因为我们还要编写一些 node 代码

• How would you like to define a style for your project?

  我们选第一个 Use a popular style guide

• Which style guide do you want to follow?

  选择 Airbnb（爱彼迎）的代码风格

• What format do you want your config file to be in?

  我们选择最灵活的配置方式：javascript

• Would you like to install them now with npm?

  选择 Y，立即安装依赖。虽然我们用的是 yarn，不应该使用 npm 安装依赖，用 npm 安装依赖还会生成对我们没有用 package-lock.json。package.lock.json 和 yarn.lock 一样都是用来锁定依赖版本的。之所以这里选择立即安装依赖是因为你如果不立即安装依赖，后面你想再用 yarn 安装依赖的时还要去查一下安装哪几个依赖，我觉得很麻烦。

安装完之后，把 node_modules, package-lock.json, yarn.lock 都删掉，使用 yarn 重新安装依赖，再升级到最新版本：

# 安装依赖
yarn
# 升级到最新版本
yarn upgrade --latest
复制代码

通过 eslint 自带的配置生成器我们生成了 .eslintrc.js ：

// 格式化后的 .eslintrc.js
module.exports = {
  env: {
    browser: true,
    es6: true,
    node: true,
  },
  extends: ['plugin:react/recommended', 'airbnb'],
  globals: {
    Atomics: 'readonly',
    SharedArrayBuffer: 'readonly',
  },
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: 2018,
    sourceType: 'module',
  },
  plugins: ['react', '@typescript-eslint'],
  rules: {},
};
复制代码

可以看到相对于非 TypeScript 项目，使用 @typescript-eslint/parser 替换掉了默认的 parser，并添加了 @typescript-eslint 插件。

我们先做以下修改：

• 查看 eslint-config-airbnb 的说明，里面提到，如果要开启 react hooks 检查，需要添加 "extends": "airbnb/hooks" 到 eslintrc.js

• 修改 parserOptions.ecmaVersion 为 2020，争做新时代的弄潮儿 😂

• 查看 @typescript-eslint/eslint-plugin 文档，里面提到我们可以通过添加 extends: 'plugin:@typescript-eslint/recommended'来开启它推荐的一些 rules，修改 extends：

  {
      extends: ['plugin:react/recommended', 'airbnb', 'airbnb/hooks','plugin:@typescript-eslint/recommended']
  }
  复制代码

• 为了让 eslint-plugin-import 能够正确解析 ts, tsx, json 后缀名，我们还需指定允许的后缀名，添加 setttings 字段，加入以下配置：

  settings: {
      'import/resolver': {
          node: {
              // 指定 eslint-plugin-import 解析的后缀名
              extensions: ['.ts', '.tsx', '.js', '.json'],
          }
      }
  }
  复制代码

• 为了让 eslint-plugin-import 能够正确解析 tsconfig.json 中的 paths 映射，我们需要安装 eslint-import-resolver-typescript：

  yarn add eslint-import-resolver-typescript -D
  复制代码

  修改 settings 字段：

  settings: {
      'import/resolver': {
          // ...
          // 配置 eslint-import-resolver-typescript 读取 tsconfig.json 的路径
          typescript: {
              directory: [resolve(__dirname, './src/tsconfig.json'), resolve(__dirname, './scripts/tsconfig.json')],
          },
      },
  }
  复制代码

在我的使用中我发现，目前 eslint-plugin-import和TypeScript搭配还是存在很多的 bug，其中的一个不能忍的 bug 就是import/extensions 这个规则不能正确处理文件后缀名：

去 eslint-plugin-import github issue 搜索关键字 import/extensions typescript 可以搜到很多相关的 issues。目前我采用的解决方案是修改 import/extension 的规则配置：

'import/extensions': [
    'error',
    'ignorePackages',
    {
        ts: 'never',
        tsx: 'never',
        json: 'never',
        js: 'never'
    },
],
复制代码

另外一个要提的 bug 就是这个 issue： no-useless-constructor: Cannot read property 'body' of null，简单来说就是目前在 eslint 搭配 typescript 相关插件时，如果 .d.ts 声明文件中如果使用了 constructor 就会报这个错。例如：

declare module 'size-plugin' {
    import { Plugin } from 'webpack';

    interface SizePluginOptions {
        writeFile?: boolean;
    }

    class SizePlugin extends Plugin {
        // 使用了 constructor 就报错
        constructor(options?: SizePluginOptions);
    }

    export = SizePlugin;
}
复制代码

目前我采用的解决办法时是添加下面两个规则：

rules: {
    'no-useless-constructor': 'off',
    '@typescript-eslint/no-useless-constructor': 'error',
},
复制代码

针对 .d.ts 文件我们还需要要禁用一些规则，我们后续会在 script 文件夹中实现和 webpack 相关的 node 脚本，针对这个文件夹也调整一些规则：

// .eslintrc.js
{
    overrides: [
        {
            files: ['**/*.d.ts'],
            rules: {
                // 多个外部模板声明中导入同一个模块会报错的 bug，例如多个 webpack 插件的声明文件中都导入 webapck
                'import/no-duplicates': 'off',
                'max-classes-per-file': 'off',
            },
        },
        {
            files: ['scripts/**/*.ts'],
            rules: {
                // node 脚本是需要使用外部依赖的
                'import/no-extraneous-dependencies': 'off',
            },
        },
    ],
}
复制代码

其它一些个人习惯的规则调整我就不提了，读者可以直接去看最终的配置：.eslintrc.js。

目前这个配置还存在一些问题，例如很多 rules 会和 prettier 冲突，后面我们会一一解决这些问题。

stylelint

A mighty, modern linter that helps you avoid errors and enforce conventions in your styles

我对于 stylelint 的了解比较少，一般都是直接参考 ant design 的 stylint 配置。添加 .stylelintrc.json 到项目根路径，copy 过来简单修改一下，：

// .stylelintrc.json
{
    "extends": ["stylelint-config-standard", "stylelint-config-rational-order"],
    "plugins": ["stylelint-order", "stylelint-declaration-block-no-ignored-properties"],
    "rules": {
        "comment-empty-line-before": null,
        "declaration-empty-line-before": null,
        "function-name-case": "lower",
        "no-descending-specificity": null,
        "no-invalid-double-slash-comments": null
    },
    "ignoreFiles": ["node_modules/**/*", "src/assets/**/*", "dist/**/*", "**/typings/**/*"]
}
复制代码

我去掉了 stylelint-config-prettier插件（后面会加上），修改了 function-name-case 规则，最后将 ignoreFiles 选项修改为 ["node_modules/**/*", "src/assets/**/*", "dist/**/*", "**/typings/**/*"]。

src/assets 文件夹准备用来保存一些资源文件，例如第三方的 css 库，并不需要 lint。stylelint 插件目前有个 bug，如果 lint 了 .d.ts 文件在某些情况会报 TypeError: Cannot read property 'buildError' of undefine 的错误，所以我也添加了 "**/typings/**/*" 来忽略 .d.ts 文件。

根据上面的配置文件，我们需要安装对应的 npm 包：

yarn add stylelint stylelint-config-standard stylelint-config-rational-order stylelint-order stylelint-declaration-block-no-ignored-properties -D
复制代码

和 eslint 一样，会与 prettier 存在冲突。

prettier

An opinionated code formatter

opinionated 可以理解为 独断专行，自以为是，其实就是说这个格式化器（formatter）不给用户做选择，就按照一套社区共识，最佳实践，最好看的的代码风格来格式化。具体表现就是提供的选项很少，我数了一下总共刚好 20 个选项。

首先我们得安装 prettier：

yarn add prettier -D
复制代码

添加 .prettierrc 到项目根路径：

{
    "trailingComma": "all",
    "tabWidth": 4,
    "semi": true,
    "singleQuote": true,
    "endOfLine": "auto",
    "printWidth": 120,
    "overrides": [
        {
            "files": "*.md",
            "options": {
                "tabWidth": 2
            }
        }
    ]
}
复制代码

简单说明下一些选项这样配置的原因：

• "trailingComma": "all"，支持在函数参数中也插入逗号

• "semi": true，个人习惯

• "singleQuote": true,，个人习惯，少敲一下 shift 难道不好吗？

• "endOfLine": "auto"，和 editorconfig 一样，按照操作系统默认的换行符来就行了

• "printWidth": 120，我觉得默认的最大行宽 80 太短了，浪费编辑器空间

• 之所以设置 markdown 文件格式化 "tabWidth": 2，是目前 prettier 在格式化 markdown 文件时，会在无序列表中插入多余的空格

  正常的无序列表应该格式化成：

  - 1
  - 2
  - 3
  复制代码

  但是不配置 tabWidth 的话， prettier 会格式化成：

  -   1
  -   2
  -   3
  复制代码

  巨丑 😤

linters 和 prettier 的冲突

这部分内容强烈建议先阅读 prettier 官方文档 Integrating with Linters 部分，官方文档往往是更新最及时，也是最权威的。

我们知道 lint 工具是用来检查代码风格的， prettier 是用来格式化代码的。想想看，如果 prettier 设置缩进为 4 个空格，而我们配置的 eslint 是要求缩进为 2 个空格，这势必导致我们格式化代码之后，eslint 会报缩进错误。

这部分内容就是为了解决 linter 规则和 prettier 的冲突问题，其实，原理很简单，就是禁用掉掉那些会和 prettier 格式化起冲突的规则。

安装 eslint 插件 eslint-config-prettier，这个插件会禁用所有会和 prettier 起冲突的规则。

yarn add eslint-config-prettier -D
复制代码

添加 'prettier' 到extends 配置：

// .eslintrc.js
{
    extends: ['plugin:react/recommended', 'airbnb', 'airbnb/hooks', 'prettier']
}
复制代码

这里注意要把 prettier 放最后面，因为这样才能让 prettier 有机会禁用前面所有的 extends 中配置的会起冲突的规则。

stylelint 也是一样，先安装插件 stylelint-config-prettier：

yarn add stylelint-config-prettier -D
复制代码

再将 "stylelint-config-prettier" 添加到 extends 数组最后面：

// .stylelintrc.json
{
    "extends": ["stylelint-config-standard", "stylelint-config-rational-order", "stylelint-config-prettier"],
}
复制代码

lint-staged

Run linters on git staged files

我们每次提交代码都要对代码先进行 lint 和格式化，确保团队的代码风格统一。为了达到每次 lint 和格式化时只处理我们修改了的代码，也就是保存在 git stage 区（暂存区）的代码。社区比较流行的方案有俩：

1. pretty-quick
2. lint-staged

我们选择使用 lint-staged，因为前者功能单一，只是提供了 prettier 格式化 stage 区代码的功能，没法配 eslint 和 stylelint。它是一个纯粹的命令行工具，只提供了一些命令行参数，不能通过配置文件来配置。lint-satged 配置更灵活，通过它我们可以同时配置 eslint，stylelint，prettier。

为了达到在我们每次 commit 的时候，都自动 lint 和格式化，我们需要给 git commit 挂个钩子，使用 husky 可以很轻松的给 git 配置钩子。

先安装 husky 和 lint-staged：

yarn add husky lint-staged -D
复制代码

在 package.json 配置 git commit 时的钩子操作:

// package.json
{
    "husky": {
        "hooks": {
            // 在执行 git commit 调用 lint-staged 命令，lint-staged 会读取 package.json 的配置
            "pre-commit": "lint-staged"
        }
    },
}
复制代码

再在 package.json 中 "ling-staged" 字段配置 lint-staged：

// package.json
{
    "lint-staged": {
        // 对于 ts,tsx,js 文件调用 eslint
        "*.{ts,tsx,js}": [
            "eslint -c .eslintrc.js"
        ],
        // 对于 scss 文件调用 stylelint
        "*.scss": [
            "stylelint --config .stylelintrc.json"
        ],
        // prettier 支持很多类型文件的格式化
        "*.{ts,tsx,js,json,scss,md}": [
            "prettier --write"
        ]
    },
}
复制代码

prettier 的 --write 参数是干嘛用的呢？举个 🌰 来说，命令行调用 prettier a.js 默认只会输出格式化后的内容到控制台，不会修改原文件，加上 --write 才会直接格式化 a.js。需要注意的一点是，可能你们看别人的教程或者一些项目中它们还加了一个 git add 步骤，然后控制台会有警告：

⚠ Some of your tasks use git add command.

lint-staged 从 V10 版本开始，任何被修改了的原 staged 区的文件都会被自动 git add，所以我们不需要自己添加 git add 。

commitlint

commitlint helps your team adhering to a commit convention. By supporting npm-installed configurations it makes sharing of commit conventions easy.

commitlint 是一个用来 lint commit message 的工具。看官网的例子：

我知道有些人提交代码喜欢直接来三个点 ...，这是很不好的习惯，到时候你想版本回退的话就傻眼了，只能看提交的时间了和 diff 了，很不利于项目管理。规范化的编写 commit message 有很多好处，可以方便我们检索提交历史，配合 conventional-changelog 直接生成 changelog，关联 github issue 等。

我们可以通过 husky + commlint 实现在 commit 的时候先检查 commit message 的规范性，如果不符合规范直接终止 commit。

安装需要的依赖：

yarn add @commitlint/cli @commitlint/config-conventional -D
复制代码

@commitlint/config-conventional 是 commitlint 官方推荐的一个 angular 风格的 commitlint 配置，提供了少量的 lint 规则，类似于 eslint 的 extend。

添加 git commit-msg 钩子：

// package.json
{
    "husky": {
        "hooks": {
            "pre-commit": "lint-staged",
            "commit-msg": "commitlint -c .commitlintrc.js -E HUSKY_GIT_PARAMS"
        }
    },
}
复制代码

当调用 commit-msg 钩子的时候，环境变量 HUSKY_GIT_PARAMS 会被临时设置为保存 commit messsge 的文件的路径，然后 commitlint 就会去 lint 这个文件中的 commit message。

添加 commlint 的配置到项目根目录新建的 .commitlintrc.js：

module.exports = {
    extends: ['@commitlint/config-conventional'],
    rules: {
        'type-enum': [
            2,
            'always',
            // 暂时定为默认值，根据自己的需求调整
            ['build', 'ci', 'chore', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test'],
        ],
    },
};

复制代码

如果你想在命令行中交互式的编辑 commit message，可以了解一下 commitizen ，我们这个项目就不配了，主要还是觉得要配置的话就要根据具体的业务去配，我们这个通用目的的模板项目就算了。我看了一下 angular 和 vue-next lint commit message 的做法，它们 commitlint 和 commitizen 俩都没配，只是在 git commit-msg 时调用了下 node 脚本校验 commit message 。

我们接着再配置自动生成 changelog，本地安装 conventional-changelog-cli：

yarn add conventional-changelog-cli -D
复制代码

添加一个 npm script：

// package.json
"scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
}
复制代码

这样我们就可以通过 npm run changelog 生成 angular 风格的 changelog 了，conventional-changelog 会读取提交历史中 fix, feat 等 type 的 commit message 自动生成 changelog。

为了说明一个和 git emoji 相关的问题，我们先来看一下 ant design 的 github 首页，注意其中 emoji 的位置：

我们知道 commit message 的格式是这样的：

// 整行叫 header。type 指的是例如: fix, feat, build 等
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
复制代码

可以看到上面图中第二个带 emoji 的 commit message 中的 emoji 是放在 header 最前面。我们知道 git emoji 的格式是：

:emoji_string:
复制代码

如果你使用下面的带 emoji 的 commit message 提交：

git commit -m ':bug: fix: xxx'
复制代码

commitlint 等工具在解析的时候应该是将第一个冒号之前的内容解析为 type，所以上面的 commit message 提交会报错说你没有填写 type。

如果不修改 commilint 的 type-enum 配置是无法通过 commitlint 的 lint，conventional-changelog-cli 也不会将上面举例的 commit mesage 提取到 changelog，它只认 fix: xxx 不认 :bug: fix: xxx。因此，在当前配置下，我们如果要插入 emoji，建议使用上图第一个带 emoji 的方式，虽然我觉得这样不好看，但目前来说是比较折中的方案。

second commit

添加几个常用用于 lint 的 npm scripts：

{
    "scripts": {
        "lint": "yarn run lint-eslint && yarn run lint-stylelint",
        "lint-eslint": "eslint -c .eslintrc.js --ext .ts,.tsx,.js {src,scripts}/**/*.{ts,tsx,js}",
        "lint-stylelint": "stylelint --config .stylelintrc.json src/**/*.scss --syntax scss",
    }
}
复制代码

可以看到我配置 eslint 和 stylelint 的 script 是用 前缀-参数 的形式，有些项目配置带参数的 script 名是用 前缀:参数 的形式，也就是用冒号做分隔符。我觉得那样不好，因为有些工具支持 yarn:scriptName 的形式来执行 npm scripts，例如 concurrently，这个工具支持调用 concurrently yarn:watch-node yarn:watch-js yarn:watch-css 来执行多个 npm scripts。那你说如果用 冒号来做分隔符，那要写就是 concurrently yarn:watch:node yarn:watch:js yarn:watch:css，看起来就很迷惑，不了解的人可能还以为后面的冒号也是 concurrently 的参数呢，所以表示带参数的 npm script 不要用冒号做分隔符。

最后再来一发 yarn upgarde --latest，养成每天升级依赖的好习惯，避免以后同时升级很多依赖出了都搞不清楚是哪个依赖升级导致的。不过公司的项目千万别这样搞，容易导致出 bug 连续加班。

到这里，从零开始配置 react + typescript 系列第二篇算是差不多了，再一次提交代码：

git add -A
git commit -m 'build: integrate eslint, stylelint, prettier, lint-staged, commi 
tlint'
# 上次 push 的时候使用 -u 参数关联了 master 分支和 github 远程仓库，这里就可以直接 push
git push
复制代码

第二篇到此结束，第三篇关于 webpack 配置的文章将是三篇中干货最多，估计也是最长的一篇，甚至有可能要整第四篇。将介绍使用 TypeScript 来编写 express + webpack 中间件作为 devServer，集成一些实用和装逼的 webpack 插件，集成和优化 antd 等内容，敬请期待...