从零开始配置 react + typescript（一）：dotfiles

以前我写过一篇文章 搭建 react + typescript + ant design 开发环境，如今看来不少内容都已通过时了。可是我看到前不久还有读者给我这篇文章点赞，不更新的话总感受坑了它们，有点过意不去。可是，若是如今让我再去配置那套环境，我确定不会再像那篇文章那样配置了，毕竟过了这么长一段时间，不少工具都在发展，个人想法也在改变，那么干脆我就再整一篇新的文章，这是我创做这篇文章的动机之一。

最近一段时间，我写过很多类型的项目，有 chrome 扩展，VSCode 扩展， electron 等，配置开发环境都是裸写的，并无使用一些 cli 工具或者第三方的项目模板。所以，我踩过很多坑，也总结了很多的经验。因此另外一个创做动机就想总结和分享一下我配置开发环境的最佳实践。

我使用的开发机和编辑器分别是 win10pro-1909 和 VSCode。

文章将按照开发一个模板项目 react-typescript-boilerplate 的时间顺序预计分红四篇来写：

1. dotfiles
2. linters 和 formatter
3. webpack
4. 第三方库集成和优化

init

搭建项目的第一步就是新建项目文件夹，而后初始化为 git 仓库：

# 新建项目文件夹
mkdir react-typescript-boilerplate
# 切换工做路径到项目文件夹
cd $_
# 初始化 git 仓库
git init

你能够将 react-typescript-boilerplate 替换成任意你须要的项目名，$_ 表示上一条命令最后的参数，这里就表示项目文件夹。

对于dotfiles 这个词， 个人理解是指那些以点 . 开头的配置文件。在我刚开始学习前端框架的时候，看到脚手架生成的一堆 dotfiles 我也是很懵逼，头皮发麻，心想怎么写个项目要这么多配置文件，写个前端项目也太麻烦了。其实存在即合理，当我了解了它们的用途以后，就可以理解它们的必要性了，并且配置文件不少从某种程度上也反应了前端构建工具生态的活跃不是。

.gitignore

建议初始化 git 仓库后第一步就是添加 .gitignore。若是你不添加，那么 VSCode 的版本控制会监控你项目中的全部文件包括 node_modules下的一堆文件，致使 CPU 和内存占用太高等问题，因此最好一开始就配置好 gitignore。配置 gitignore 建议使用 VSCode 的 gitignore 扩展。使用方式很简单：ctrl+shift+p 唤出命令面板，调用 Add gitignore 命令，而后选择不一样类型项目的 ignore 配置，能够屡次追加。

我通常添加的项目类型包括：Node, VisualStudioCode, JetBrains, Windows, Linux, macOS，你能够根据本身的须要添加其它的项目类型例如 SublimeText，Vim。虽然我是用 VSCode 作开发，可是考虑到别人开发这个项目的时候可能用的就是 WebStorm 了，因此就添加了和 JetBrains IDE 相关的 ignore 配置。这个扩展的原理是经过拉取开源项目 gitignore 的 gitignore 配置，须要注意的是咱们要删除其中两个配置项 typings/ 和 Icon。这两个配置项明显是须要添加到 git 版本控制的，typings 文件夹咱们会用来保存 ts 的类型定义文件，icon 文件夹咱们通常用来保存图标。

.editorconfig

经过配置 editorconfig，咱们可让多个开发人员，使用不一样的编辑器时，代码格式化风格仍然保持一致。有些 IDE 例如 IDEA 是直接内置了 editorconfig 规范，有些编辑器如 VSCode 则须要安装对应的插件去支持。

咱们拿 VSCode 和 IDEA 来作个测试，下面这张图是左边是测试文件 index.js，右边是 editorcofig 配置，注意到我刻意把缩进设置成了 3 个空格。VSCode 是能够设置它格式化代码时使用的 formatter 的，若是你不设置，那就是用内置的 formatter，也就是：

"[javascript]": {
    "editor.defaultFormatter": "vscode.typescript-language-features"
 }

在我 alt + shift + f 格式化以后能够看到，VSCode 遵循了 editorconfig 的配置将代码的缩进格式化成了 3 个空格。

我继续在 IDEA 中打开这个项目后经过 ctrl + alt + l 格式化，意料之中也是格式化成了三个空格，我就不贴图了，和上面同样。

有人可能会想，prettier 也是格式化工具，为何同一个项目配置俩格式化工具（后面咱们还要配置 prettier）？事实上，能够看到有些著名的开源项目如 react, VSCode 就是两个都用了。其实想一想看：到最后代码格式化功能确定是要交给 prettier 去干的，通常都是用 lint-staged，每次只把修改过的代码格式化。那是否就是说， editorconfig 是没有用的配置呢？

固然是有用的，本质上 editorconfig 和 prettier 的区别在于：editorconfig 是主动做用于编辑器的，你添加了 .editoronfig 文件，调用 VSCode 的格式化，格式化结果就是 .editorconfig 配置的风格。而 prettier 只是一个命令行工具，须要咱们去调用它，它才会格式化代码，它自己是被动的。若是你不配置 editorconfig，那当用户修改了一个文件，调用 VSCode 快捷键手动格式化代码，提交时又被 prettier 格式化一遍，由于 VScode 内置的 formatter 和 prettier 风格不同，致使我明明手动格式化了，怎么提交后还被修改了。配置 editorconfig ，而且使其和 prettier 的风格保持一致，就能够解决前面提到的屡次格式化结果不同的问题。事实上， react 就是这样干的。

其实，当用户配置了 prettier 做为 VSCode 的 javascript formatter， editorconfig 配置就没什么用了。

说了那么多，其实配置起来很是简单，建议安装 VSCode 扩展 EditorConfig for VS Code，安装以后能够经过命令 Generate .editorcofig 生成默认的配置，我的建议最后加上一行 end_of_line = unset，让行尾换行符直接遵照操做系统的换行符。

root = true

[*]
indent_style = space
indent_size = 4
charset = utf-8
trim_trailing_whitespace = false
insert_final_newline = false
# 加上这一行
end_of_line = unset

.nvmrc

nvm (node version manager) 是 node 的版本管理工具，在 windows 上使用 nvm 要安装另外一个工具 nvm-windows。

.nvmrc 是 nvm 的配置文件，不少工具在判断项目的 node 版本的时候会读取这个配置，例如 travis CI。若是项目根路径有 .nvmrc 的话就不用在 .travis.yml 中指定 node 的版本了。建议平时开发使用最新的 LTS 版本，新版本不但支持的 ES 特性更多，性能通常也有提高，bug 通常也更少。不建议开发项目时选择最新的非 LTS 版，有些包例如 bcrypt 在最新的非 LTS 版根本就不支持。以前我一个朋友就碰到安装 bcrypt 安装不了的问题，研究到最后发现是由于 bcrypt 根本就不支持最新的非 LTS 的 node。

.npmrc

众所周知，因为不可抗之力，国内不管是访问 github 仍是下载 npm 包都是蜗速。对于国内用户而言，首先咱们要作的一件事就是将 npm 源设置淘宝源。配置 npm 源建议使用 nrm：

# 全局安装 nrm，
yarn global add nrm
# 或者使用 npm 安装，install 能够简写成 i
npm i -g nrm
# 设置使用淘宝源
nrm use taobao

经过 nrm ls 咱们还能够看到其它的一些源:

$ nrm ls

  npm -------- https://registry.npmjs.org/
  yarn ------- https://registry.yarnpkg.com/
  cnpm ------- http://r.cnpmjs.org/
* taobao ----- https://registry.npm.taobao.org/
  nj --------- https://registry.nodejitsu.com/
  npmMirror -- https://skimdb.npmjs.com/registry/
  edunpm ----- http://registry.enpmjs.org/

测试一下其中几个常见的源的丢包率，淘宝源一骑绝尘啊：

.npmrc 是给 npm 用的配置文件，固然你若是使用 yarn，yarn 也会遵照 .npmrc 配置，虽然 yarn 有专门的配置文件 .yarnrc。

咱们知道有些 npm 包在安装时是须要下载一些二进制依赖文件，其中有几个坑货像 node-sass，electron，bcrypt 还须要配置代理才能下载。为了让让别人合做开发项目的时候能顺利安装它们，咱们能够在 .npmrc 中直接设置它们的镜像地址，添加 node-sass 的镜像地址：

# .npmrc
SASS_BINARY_SITE=http://npm.taobao.org/mirrors/node-sass

LICENSE

根据你的项目性质，去网站 choose a license 选择一个合适的 license， 复制后粘贴到项目根路径的 LICENSE 或 LICENSE.txt 文件里面，修改一些配置便可。这里我选择宽松的 MIT 协议，修改其中的年份和做者名：

MIT License

Copyright (c) [2020] [YuTengjing]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

package.json

生成 package.json 的时候须要考虑一个问题，你是打算使用 yarn，npm，仍是 cnpm？

最近貌似还发布了 yarn2 ，不过我确定不会考虑 yarn2 的，先不说有不少 bug ，还不够成熟，社区的接受度仍是一个问题，yarn2 和 yarn1 差异很大。

讲真我以为 npm 是真的设计的很屎，不知道最开始为何会设计成安装包默认不会添加到 dependencies，使用缓存这么容易想到的设计仍是 yarn 独创的，锁定版本也是抄 yarn 的。

yarn 用起来舒服多了。可是 yarn 在 windows 常常有 hash 值对不上而后安装不了的 bug，搞得我很烦，看了一下 github 仓库，将近 2000 个 issues。

最近我从新试用了一下 cnpm，让我意外的是下载速度是真的快，一样的使用淘宝源，cnpm 比 yarn 还要快不少。可是我以为 cnpm 安装以后，node_modules 看起来很乱，多了不少乱七八槽的依赖。

由于我有点洁癖，因此 yarn 和 cnpm 我站 yarn。

package.json 是用来管理 npm 包的配置文件，生成 package.json 最简单的方式就是来一句 yarn init -y，直接就生成一个默认的 package.json。

{
  "name": "react-typescript-boilerplate",
  "version": "1.0.0",
  "main": "index.js",
  "author": "YuTengjing <ytj2713151713@gmail.com>",
  "license": "MIT"
}

咱们来修改下这个默认的配置：

由于咱们这个项目不打算发布到 npm，因此 private 设置为 true。

这个 main 入口对于咱们这个模板项目来讲没什么意义，直接删了。

修改一下 author 和 repository 的格式就是下面这样了：

{
  "name": "react-typescript-boilerplate",
  "version": "1.0.0",
  "description": "A boilerplate for react + typescript development",
  "private": true,
  "author": {
    "name": "YuTengjing",
    "url": "https://github.com/tjx666",
    "email": "ytj2713151713@gmail.com"
  },
  "repository": {
    "type": "git",
    "url": "git@github.com:tjx666/react-typescript-boilerplate.git"
  },
  "license": "MIT",
  "scripts": {}
}

settings.json

若是你使用的是 VSCode，那么能够添加 VSCode 的项目配置文件 .vscode/settings.json。新建 .vscode 文件夹并在其中建立 settings.json文件。settings.json 虽而后缀名是 .json，实际上是 jsonc 格式的文件，jsonc 和 json 文件的区别就在于 jsonc 容许添加注释，jsonc 的这个c 就是 comment（注释）的意思嘛。暂时添加如下内容：

{
    // 指定哪些文件不参与搜索
    "search.exclude": {
        "**/node_modules": true,
        "dist": true,
        "yarn.lock": true
    },
    // 指定哪些文件不被 VSCode 监听，预防启动 VSCode 时扫描的文件太多，致使 CPU 占用太高
    "files.watcherExclude": {
        "**/.git/objects/**": true,
        "**/.git/subtree-cache/**": true,
        "**/node_modules/*/**": true,
        "dist": true,
        "yarn.lock": true
    },
    // 配置 VScode 使用 prettier 的 formatter
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[javascriptreact]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[typescript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[typescriptreact]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[json]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[jsonc]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[html]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[css]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[less]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[scss]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[markdown]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
}

.travis.yml

我选择使用最流行的开源 CI 工具 travis CI，在 github 上新建完仓库后就能够去 travis CI 官网，先同步 github 帐号信息，而后搜索激活新建的仓库。

在项目根目录新建 .travis.yml 文件，加入如下内容：

language: node_js
cache:
  - yarn
install:
  - yarn
script:
  - yarn test

很是简单的配置，只是负责自动化测试。由于目前没有测试，咱们添加一个 echo 语句到 npm scripts 里面：

// package.json
"scripts": {
    "test": "echo 'skip test...'"
}

README.md

README.md 就是项目的说明书，每一个文件夹中的 README.md 在 github 上都会被渲染到页面上。咱们在项目根目录添加的 README.md 天然就会被渲染到仓库的首页。

咱们添加一些实用的 badges（徽章），例如 travis CI 的 build 状态，dependencies 版本是否过时等 。badge 本质上就是一个连接，只不过文字部分换成了 svg 渲染的图片。

添加如下内容：

<div align="center">

# react-typescript-boilerplate

[![Build Status](https://travis-ci.org/tjx666/react-typescript-boilerplate.svg?branch=master)](https://travis-ci.org/tjx666/react-typescript-boilerplate) [![dependencies Status](https://david-dm.org/tjx666/react-typescript-boilerplate/status.svg)](https://david-dm.org/tjx666/react-typescript-boilerplate) [![devDependencies Status](https://david-dm.org/tjx666/react-typescript-boilerplate/dev-status.svg)](https://david-dm.org/tjx666/react-typescript-boilerplate?type=dev) [![Known Vulnerabilities](https://snyk.io/test/github/tjx666/react-typescript-boilerplate/badge.svg?targetFile=package.json)](https://snyk.io/test/github/tjx666/react-typescript-boilerplate?targetFile=package.json) [![Percentage of issues still open](https://isitmaintained.com/badge/open/tjx666/react-typescript-boilerplate.svg)](http://isitmaintained.com/project/tjx666/react-typescript-boilerplate')

A boilerplate for react + typescript development

</div>

使用 div 的 align 属性将标题，徽章和描述居中。其实通常的项目还要加 CHANGELOG.md（更新日志）文件，这项目感受没啥必要。

first commit

到这感受就能够作第一次提交了：

# 添加远程仓库地址
git remote add github git@github.com:tjx666/react-typescript-boilerplate.git
# 添加全部修改到暂存区
git add -A
# 提交，使用 :tada: emoji
git commit -m ":tada: first commit, add some dotfiles"
# 推送到 github，关联 github 远程仓库和 master 分支，下次仍是 master 分支就能够直接 git push 了
git push github -u master

推荐使用 gitmoji-cli 或者直接使用 VSCode 扩展 Gitmoji Commit 生成 git emoji。

下一篇 将继续介绍 linters 和 formatter 的配置。

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

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