從零開始配置 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 的配置。