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

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

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

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

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

1. dotfiles
2. linters 和 formatter
3. webpack

init

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

mkdir react-typescript-boilerplate && cd $_ && git init
复制代码

你能够将 react-typescript-boilerplate 替换成任意你须要的项目名，这里的 $_ 表示上一条命令最后的参数，使用 git init 初始化 git 仓库。

对于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 版本控制的，没有 ts 项目的声明文件根本就没办法编译成功嘛，icon 文件夹咱们常常用来存图标。

.editorconfig

EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.

editorconfig 本质上就是一种跨编辑器和 IDE 的，使用 .editorconfig 文件来描述代码风格的工具。 什么叫 跨编辑器和 IDE，其实就是说支持了 editorconfig 的编辑器和 IDE 都应该遵照 .editorconfig 中的配置来格式化代码。咱们拿 VSCode 和 IDEA 来作个测试就知道了。

下面这张图是左边是测试文件 index.js，右边是 .editorcofig 配置，注意到我刻意把缩进设置成了 3 个空格。因为格式化功能会受到 prettier 的影响，我暂时先将 javascript 文件的 formatter 设置成 VSCode 内置的。

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

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

有人可能会想，prettier 也是格式化工具，为何同一个项目配置俩格式化工具（后面咱们还要配置 prettier）？事实上，能够看到有些著名的开源项目如 react, VSCode 就是两个都用了。其实想一想看，到最后代码格式化功能确定是要交给 prettier 去干的，通常都是用 lint-staged，每次只把修改过的代码格式化。因此，本质上，editorconfig 对于高级用户来讲就是多余的，纯粹是为了照顾那些不会配置 formatter 的人。

之因此还要配置editorconfig ，我以为是为了：当用户没有配置编辑器或者 IDE 的 formatter 时，使得其格式化风格和 prettier 格式化风格保持一致。有些用户可能并无没配置 VSCode 的 javascript 的 formatter，因此 VSCode 是使用默认的格式化器：

"[javascript]": {
    "editor.defaultFormatter": "vscode.typescript-language-features"
 }
复制代码

格式化效果就是上面那张图。当用户配置了 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

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

// 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
复制代码

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。

LICENSE

根据你的项目性质，去网站 choose a license 选择一个合适的 license， 复制后粘贴到项目根路径的 LICENSE 文件里面，修改一些配置便可。这里我选择宽松的 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 是 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
    }
}
复制代码

.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
git push github -u master
复制代码

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

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