搭建 react + typescript + ant design 开发环境

9102 年了，前端工程化发展在 nodejs 的基础上已经发展的非常完善了，各种前端构建 工具 层出不穷。ES6 编译器 babel，css 辅助工具 postcss/scss/less，代码风格检测工具 eslint/prettier/stylelint，git 辅助工具 husky/lint-staged/commitizen/commitlint/，打包工具 webpack/gulp/grunt，测试工具 jest/mocha 等等。这么多构建工具每次写项目都去配置一遍那也太浪费时间了，自己维护一套模板有得时不时去更新。比较方便的配置开发环境还是使用 cli 或者一些热门的 bolierplate。本篇文章将以 react 官方维护的 cli 工具 create-react-app （简称 cra）为基础，以不 eject 的方式去配置 ant design，以及一些 cra 并没有内置的辅助工具。

初始化项目并添加 typescript 支持

Typescript 在近两年以惊人的速度被越来越多的开发者和开源项目所采用，我在使用 typescript 开发了一个项目之后也被 typescript 圈粉了。使用 typescript 开发带来的智能提示可以很大程度上杜绝手贱的发生，大多数情况我们都不需要查文档了，以及 typescript 中的一些 javascript 中没有的语法特性如枚举，使得项目组织可以非常的优雅。从 angular2 默认使用 typescript 开发，到如今 vue3 使用 typescript 重写也能看出 typescript 在前端界的地位将越来越重要。9102，除非是非常小的项目，否则上 typescript 绝对是明智之举。

我的开发环境：

node: 10.15.3 LTS
yarn: 1.15.2
editor: visual studio code

cra 内置了 typescript 支持，只需要在初始化项目时指定 --typescript 参数即可。

npx create-react-app my-app --typescript

# or

yarn create react-app my-app --typescript
复制代码

如果 cra 项目已经存在，先安装以下 ts types 依赖：

npm install --save typescript @types/node @types/react @types/react-dom @types/jest

# or

yarn add typescript @types/node @types/react @types/react-dom @types/jest
复制代码

然后将 .js 结尾的文件重命名为 .tsx 即可。

更多关于在 cra 中使用 ts 的信息查看官方文档：Adding TypeScript

配置 ant design

安装 ant design 依赖

现在从 yarn 或 npm 安装并引入 antd。

$ yarn add antd
复制代码

配置 ant design css 按需加载

配置 css 按需加载的方式有很多，归根到底就是修改 cra 的 webpack 配置。可以采用暴露 cra webpack 配置的方式，使用 yarn eject 命令即可在项目根目录下暴露出项目的 webpack 配置，配置保存在 config 文件夹下面。我记得 cra 早期版本 eject 之后暴露的配置是拆分成两份 webpack.config.dev.js ， webpack.config.prod.js 。最新的 cra 配置被合并到一个配置文件里面了，就一个配置文件，通过一个计算出的环境（development/producation）来动态生成 webpack 配置，这种方式我觉得配置起来更麻烦了，而且eject 是不可逆的，采用 eject 来修改 webpack 配置需要慎重考虑。这种方式的好处就是 webpack 配置你可以直接修改，所以基本上没什么配置不能通过这种方式来加载。

这里我采用社区的 cra 配置解决方案： react-app-rewired 。

引入 react-app-rewired 并修改 package.json 里的启动配置。由于新的 react-app-rewired@2.x 版本的关系，你还需要安装 customize-cra 。

$ yarn add react-app-rewired customize-cra
复制代码

/* package.json */
"scripts": {
-   "start": "react-scripts start",
+   "start": "react-app-rewired start",
-   "build": "react-scripts build",
+   "build": "react-app-rewired build",
-   "test": "react-scripts test",
+   "test": "react-app-rewired test",
	"eject": "react-scripts eject"
}
复制代码

在项目根目录新建 config 文件夹，并在 package.json 中添加配置：

"config-overrides-path": "config/config-overrides.js"
复制代码

然后再在其中创建一个 config-overrides.js 用于修改默认配置。

module.exports = function override(config, env) {
  // do stuff with the webpack config...
  return config;
};
复制代码

使用 babel-plugin-import

babel-plugin-import 是一个用于按需加载组件代码和样式的 babel 插件（原理），现在我们尝试安装它并修改 config-overrides.js 文件。

$ yarn add babel-plugin-import
+ const { override, fixBabelImports } = require('customize-cra');

- module.exports = function override(config, env) {
-   // do stuff with the webpack config...
-   return config;
- };
+ module.exports = override(
+   fixBabelImports('import', {
+     libraryName: 'antd',
+     libraryDirectory: 'es',
+     style: 'css',
+   }),
+ );
复制代码

按下面的格式引入 ant design 组件。

// src/App.js
  import React, { Component } from 'react';
- import Button from 'antd/lib/button';
+ import { Button } from 'antd';
  import './App.css';

  class App extends Component {
    render() {
      return (
        <div className="App">
          <Button type="primary">Button</Button>
        </div>
      );
    }
  }

  export default App;
复制代码

最后重启 yarn start 访问页面，antd 组件的 js 和 css 代码都会按需加载，你在控制台也不会看到这样的警告信息。关于按需加载的原理和其他方式可以阅读这里。

自定义主题

按照配置主题 的要求，自定义主题需要用到 less 变量覆盖功能。我们可以引入 customize-cra 中提供的 less 相关的函数 addLessLoader 来帮助加载 less 样式，同时修改 config-overrides.js 文件如下。

$ yarn add less less-loader
复制代码

- const { override, fixBabelImports } = require('customize-cra');
+ const { override, fixBabelImports, addLessLoader } = require('customize-cra');

module.exports = override(
  fixBabelImports('import', {
    libraryName: 'antd',
    libraryDirectory: 'es',
-   style: 'css',
+   style: true,
  }),
+ addLessLoader({
+   javascriptEnabled: true,
+   modifyVars: { '@primary-color': '#1DA57A' },
+ }),
);
复制代码

这里利用了 less-loader 的 modifyVars 来进行主题配置， 变量和其他配置方式可以参考配置主题 文档。

修改后重启 yarn start 。

添加sass 支持

react-scripts@2.0.0 内置了 sass 支持，我们只需要安装 node-sass 依赖即可。

$ npm install node-sass --save
$ # or
$ yarn add node-sass
复制代码

然后就可以把项目模板中的 css 文件后缀改成 .scss 了。注意是 .scss 不是 .sass 哦， .sass 是 yml 的写法。

添加editorconfig

editorconfig 帮助我们约束多个开发者在同一个项目中代码风格，更重要的是它是跨编辑器，IDE 的。

在 vscode 中使用时可以安装 EditorConfig for VS Code 插件，然后 ctrl + shift + p 调出命令面板，输入 editorconfig 就可以看到 Generator .editorconfig 命令，选择命令后根目录就会生成初始的 .editorconfig 文件。

添加 nvmrc

在项目根目录创建文件 .nvmrc ，再将 node -v 的结果复制进去就可以了。或者直接在项目根目录执行下面的命令。

$ node -v > .nvmrc
复制代码

添加 .gitignore

cra 默认已经帮我们添加了 .gitignore ，我们可以再添加一些比如 src/assets/videos/* 。使用 vscode 的插件gitignore 我们可以很方便的追加其它要忽略的文件，比如可以选择再添加 VisualStudioCode ， Windows 的忽略文件。

配置 linters

ESLint

ESLint 可以约束团队成员的代码风格，并且找出一些容易产生问题的代码。vscode 中安装 ESLint 后可以在 PROBLEMS 面板中看到 ESLint 提示的各种错误。ESLint 自带的 autoFix 也挺好用的，不过我一般会直接让 prettier 去在提交代码时格式化一遍。

cra 默认集成了 ESLint，要让编辑器正确提示 ESLint 错误，需要在项目根目录添加 .eslintrc.json 。内容如下：

{
  "extends": "react-app"
}
复制代码

为了让 vscode 的 eslint 插件启用 typescript 支持，需要添加下面的配置到 .vscode/settings.json 中。

{
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    { "language": "typescript", "autoFix": true },
    { "language": "typescriptreact", "autoFix": true }
  ]
}
复制代码

集成prettier

Prettier is an opinionated code formatter

opinionated 有武断，自以为是的意思，这里应该理解为 prettier 提供的配置很少，有点强制约定代码风格的意思。

使用 prettier 来格式化我们的代码建议在 git commit 时自动触发就好了，要给 git 设置钩子，我们可以使用 husky 工具。

npm install --save husky lint-staged prettier
复制代码

lint-staged 是一个提高 lint 工具速度的工具，他的作用就和它的名字一样，lint-staged 可以让 lint 工具只 lint 保存在 stage 区的代码，从而加快 lint 速度。

接着配置 husky 和 lint-staged。在 package.json 中加入下面内容。

"husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "src/**/*.{js,jsx,ts,tsx,json,css,scss,md}": [
      "prettier --single-quote --write",
      "git add"
    ]
  },
复制代码

如果还需要配置 prettier，在项目根目录添加配置文件 .prettierrc.js。内容如下：

// prettier.config.js or .prettierrc.js
module.exports = {
    trailingComma: "es5",
    tabWidth: 4,
    semi: false,
    singleQuote: true
};
复制代码

集成stylelint

stylelint 我主要参考了 ant design 的配置。

yarn add -D stylelint
复制代码

在根目录添加 stylelint 配置文件 .stylelintrc.json 或者 package 添加字段 "stylelint"，内容如下：

{
  "extends": [
    "stylelint-config-standard",
    "stylelint-config-rational-order",
    "stylelint-config-prettier"
  ],
  "plugins": ["stylelint-order", "stylelint-declaration-block-no-ignored-properties"],
  "rules": {
    "comment-empty-line-before": null,
    "function-name-case": ["lower"],
    "no-invalid-double-slash-comments": null,
    "no-descending-specificity": null,
    "declaration-empty-line-before": null
  },
    "ignoreFiles": []
}
复制代码

安装上面配置中使用的插件。

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

修改 lint-staged 配置为：

"lint-staged": {
    "src/**/*.{js,jsx,ts,tsx,json,css,scss,md}": [
      "prettier --single-quote --write",
      "git add"
    ],
    "src/**/*.css": "stylelint",
    "src/**/*.scss": "stylelint --syntax=scss"
},
复制代码

配置 commitlint

安装校验工具 @commitlint/cli。

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

安装符合Angular风格的校验规则。

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

package.json 添加 "commitlint" 字段并设置：

"commitlint": {
    "extends": [
      "@commitlint/config-conventional"
    ]
}
复制代码

package.json 中 husky 配置修改为：

"husky": {
        "hooks": {
            "pre-commit": "lint-staged",
            "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
        }
},
复制代码

最后

添加一些常用的文件夹。我一般默认添加 components，pages，stores，utils，styles 这几个文件夹。做到这里，我们的项目的开发环境算是配置好了，接下来你应该修改 cra 生成的模板项目的网站图标和全局样式等，然后进行业务开发。

我有个完全按照上面的步骤配置好的项目： mini-shop ，需要的可以查看我第二次提交时的代码，因为 cra 默认帮我们提交了一次，我配置完开发环境再提交就是第二次了。

参考资料：

1. create-react-app 官方文档
2. Cz工具集使用介绍 - 规范Git提交说明