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

2020年2月2日  23分钟

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

项目地址：react-typescript-boilerplate

eslint

Find and fix problems in your JavaScript code

eslint-react-hooks.png

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

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

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

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

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，这篇文章说的很细。

安装完之后，把 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 插件：

yarn add eslint-plugin-eslint-comments eslint-plugin-promise eslint-plugin-unicorn -D

eslint-plugin-eslint-comments 用于 lint eslint 指令注释，例如检测出无用的 eslint-disable 注释。eslint-plugin-promise 按照最佳实践 lint 你的 promise 代码，eslint-plugin-unicorn 是 sindresorhus 大佬开发的一个 eslint 插件，提供了循环依赖检测，文件名大小写风格约束等非常实用的规则集合。

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

import-extension.png

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

'import/extensions': [
    '2,
    '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 就报错：no-useless-constructor: Cannot read property 'body' of null
        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: {
                'import/no-duplicates': OFF,
            },
        },
        {
            files: ['scripts/**/*.ts'],
            rules: {
                '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

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

// .stylelintrc.json
{
    "extends": [
        "stylelint-config-standard",
        "stylelint-config-rational-order",
        "stylelint-config-prettier"
    ],
    "plugins": [
        "stylelint-order",
        "stylelint-declaration-block-no-ignored-properties",
        "stylelint-scss"
    ],
    "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
    },
     // 加 "**/typings/**/*" 的原因：https://github.com/stylelint/vscode-stylelint/issues/72
    "ignoreFiles": ["node_modules/**/*", "src/assets/**/*", "dist/**/*", "**/typings/**/*"]
}

src/assets 文件夹准备用来保存一些资源文件，例如第三方的 css 库，并不需要 lint。VSCode 的 stylelint 插件目前有个 bug，默认居然会 lint .d.ts 文件然后报错，所以我也添加了 "**/typings/**/*" 来忽略 .d.ts 文件：

vscode stylelint bug

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

yarn add stylelint stylelint-config-standard stylelint-config-rational-order stylelint-config-prettier stylelint-order stylelint-declaration-block-no-ignored-properties stylelint-scss -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": 100,
    "overrides": [
        {
            "files": "*.md",
            "options": {
                "tabWidth": 2
            }
        }
    ]
}

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

linters 和 prettier 的冲突

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

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

conflict

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

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

yarn add eslint-config-prettier -D

添加 'prettier'，'prettier/react'，'prettier/@typescript-eslint' 到extends 配置：

// .eslintrc.js
{
    extends: [
        'airbnb',
        'airbnb/hooks',
        'plugin:eslint-comments/recommended',
        'plugin:import/typescript',
        'plugin:react/recommended',
        'plugin:@typescript-eslint/recommended',
        'plugin:unicorn/recommended',
        'prettier',
        // 专门支持了 eslint-plugin-react
        'prettier/react',
        // 专门支持了 @typescript-eslint/eslint-plugin
        'prettier/@typescript-eslint',
    ],
}

这里注意要把 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

git-stage.png

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

  1. pretty-quick
  2. lint-staged

我们选择使用 lint-staged，因为 pretty-quick功能单一，只是提供了 prettier 格式化 stage 区代码的功能，没法配 eslint 和 stylelint 使用，还不能通过配置文件来配置。lint-staged 更灵活，通过它我们可以同时配置 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 中 lint-staged 的配置
            "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"
        ],
        // 对于 css,less,scss 文件调用 stylelint
        "*.{css,less,scss}": [
            "stylelint --config .stylelintrc.json"
        ],
        // prettier 支持很多类型文件的格式化
        "*.{ts,tsx,js,json,html,yml,css,less,scss,md}": [
            "prettier --write"
        ]
    },
}

prettier 的 —write 参数是干嘛用的呢？举个 🌰 来说，命令行调用 prettier a.js 默认只会输出格式化后的代码到控制台，不会修改原文件，加上 --write 才会将格式化后的代码写到 a.js。需要注意的一点是，可能你们看别人的教程或者一些项目中他们配置 lint-staged 还加了一个 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 的工具。看官网的例子：

commitlint

我知道有些人提交代码喜欢直接来三个点 ...，这是很不好的习惯，这样你就完全没有利用到 commit message，很不利于项目管理。规范化的编写 commit message 有很多好处，可以方便我们检索提交历史，配合 conventional-changelog 直接生成 changelog，关联 github issue 等。

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

安装需要的依赖：

yarn add @commitlint/cli @commitlint/config-conventional -D

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

它默认支持的提交类型为：

["build", "ci", "chore", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test"]

添加 commitlint 的配置到项目根目录的 .commitlintrc.js：

// .commitlintrc.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      // 比默认值多了个 deps，用于表示依赖升级，降级，新增等提交
      [
        'build',
        'ci',
        'chore',
        'deps',
        'docs',
        'feat',
        'fix',
        'perf',
        'refactor',
        'revert',
        'style',
        'test',
      ],
    ],
  },
};

添加 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 message 的文件的路径，然后 commitlint 就会去 lint 这个文件中的 commit message。

如果你想在命令行中交互式的编辑 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。

我们接着讨论一个使用了 commitlint 后如何插入 emoji 的问题，我们知道 commit message 的格式是这样的：

// 整行叫 header
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

// 举个例子，某次提交的 commit message 是：feat(component): add component Navbar
// feat 是 type
// component 是 scope
// 'add component Navbar' 是 subject
// 这里没有 body 和 footer

我们知道 git emoji 的格式是：

:emoji_string:

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

git commit -m ':bug: fix: xxx'

commitlint 等工具在解析的时候应该是将第一个冒号之前的内容解析为 type，也就是说会把 emoji 左边冒号之前的内容解析为 type，那这样解析的话 type 就是空字符串了，所以使用上面的 commit message 提交会报错说你没有填写 type。

如果不修改 commitlint 的 type 配置是无法通过 commitlint 的，解决办法之一是添加一个 type :bug: fix，但是这样的话 conventional-changelog-cli 不会将 commit message 提取到 changelog，它只认 fix: xxx 不认 :bug: fix: xxx。因此，在当前配置下，我们如果要插入 emoji，建议使用下图的方式，虽然我觉得这样不好看，但目前来说是比较折中的方案。

git commit -m "chore: :memo: improve docs and config json"

commitlint git 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。

假设你有多个 npm scripts，分别是：yarn:watch-node，yarn:watch-node，yarn:watch-css，这个工具支持一条命令来并行执行它们：

concurrently yarn:watch-node yarn:watch-js yarn:watch-css

那你说如果用冒号来做分隔符，那要写就是：

concurrently yarn:watch:node yarn:watch:js yarn:watch:css

看起来就很迷，不了解的人可能还以为后面的冒号也是 concurrently 的参数呢，所以表示带参数的 npm script 不要用冒号做分隔符。

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

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

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

第二篇到此结束，第三篇关于 webpack 配置的文章将是四篇中干货最多，估计也是最长的一篇。将介绍使用 TypeScript 来编写 express + webpack devServer 中间件 作为 devServer，集成一些实用和酷炫的 webpack 插件，优化 babel 配置，生产环境打包优化等内容。

要想了解更多细节，建议直接看源码，项目地址：react-typescript-boilerplate。如果觉得本文对你有用，不妨赏颗 star 😁。对本文内容有疑问或者有什么改进的地方欢迎通过评论和邮件交流。

本文为原创内容，首发于个人博客，转载请注明出处。