從零開始配置 react + typescript（一）：dotfiles

時間  2021-08-13
標籤 javascript css html 前端 java node react webpack git github 欄目 React 简体版
原文   原文鏈接

以前我寫過一篇文章 搭建 react + typescript + ant design 開發環境，如今看來不少內容都已通過時了。可是我看到前不久還有讀者給我這篇文章點贊，不更新的話總感受坑了它們，有點過意不去。可是，若是如今讓我再去配置那套環境，我確定不會再像那篇文章那樣配置了，畢竟過了這麼長一段時間，不少工具都在發展，個人想法也在改變，那麼幹脆我就再整一篇新的文章，這是我創做這篇文章的動機之一。javascript

最近一段時間，我寫過很多類型的項目，有 chrome 擴展，VSCode 擴展， electron 等，配置開發環境都是裸寫的，並無使用一些 cli 工具或者第三方的項目模板。所以，我踩過很多坑，也總結了很多的經驗。因此另外一個創做動機就想總結和分享一下我配置開發環境的最佳實踐。css

我使用的開發機和編輯器分別是 win10pro-1909 和 VSCode，使用的全部依賴都是最新的，而且文章會不定時更新，確保具備時效性。html

文章將按照開發一個模板項目的時間順序預計分紅四篇來寫：前端

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

項目地址：react-typescript-boilerplatejava

init

搭建項目的第一步就是新建項目文件夾，而後初始化爲 git 倉庫：node

# 新建項目文件夾
mkdir react-typescript-boilerplate
# 切換工做路徑到項目文件夾
cd $_
# 初始化 git 倉庫
git init
複製代碼

你能夠將 react-typescript-boilerplate 替換成任意你須要的項目名，$_ 表示上一條命令最後的參數，這裏就表示項目文件夾。react

對於 dotfiles 這個詞， 個人理解是指那些以點 . 開頭的配置文件。在我剛開始學習前端框架的時候，看到腳手架生成的一堆 dotfiles 我也是很懵逼，頭皮發麻，心想怎麼寫個項目要這麼多配置文件，寫個前端項目也太麻煩了。其實存在即合理，當我瞭解了它們的用途以後，就可以理解它們的必要性了，並且配置文件不少從某種程度上也反應了前端構建工具生態的活躍不是。webpack

.gitignore

建議初始化 git 倉庫後第一步就是添加 .gitignore。若是你不添加，那麼 VSCode 的版本控制會監控你項目中的全部文件包括 node_modules下的一堆文件，致使 CPU 和內存佔用太高等問題，因此最好一開始就配置好 gitignore。配置 gitignore 建議使用 VSCode 的 gitignore 擴展。使用方式很簡單：ctrl+shift+p 喚出命令面板，調用 Add gitignore 命令，而後選擇不一樣類型項目的 ignore 配置，能夠屢次追加。git

gitignore.gif

我通常添加的項目類型包括：Node, VisualStudioCode, JetBrains, Windows, Linux, macOS，你能夠根據本身的須要添加其它的項目類型例如 SublimeText，Vim。雖然我是用 VSCode 作開發，可是考慮到別人開發這個項目的時候可能用的就是 WebStorm 了，因此就添加了和 JetBrains IDE 相關的 ignore 配置。這個擴展的原理是經過拉取開源項目 gitignore 的 gitignore 配置，須要注意的是咱們要刪除其中兩個配置項 typings/ 和 Icon。這兩個配置項明顯是須要添加到 git 版本控制的，typings 文件夾咱們會用來保存 ts 的類型定義文件，icon 文件夾咱們通常用來保存圖標。github

.editorconfig

經過配置 editorconfig，咱們可讓多個開發人員，使用不一樣的編輯器時，代碼格式化風格仍然保持一致。有些 IDE 例如 IDEA 是直接內置了 editorconfig 規範，有些編輯器如 VSCode 則須要安裝對應的插件去支持。

咱們拿 VSCode 和 IDEA 來作個測試，下面這張圖是左邊是測試文件 index.js，右邊是 editorcofig 配置，注意到我刻意把縮進設置成了 3 個空格。VSCode 是能夠設置它格式化代碼時使用的 formatter 的，若是你不設置，那就是用內置的 formatter，也就是：

"[javascript]": {
    "editor.defaultFormatter": "vscode.typescript-language-features"
 }
複製代碼

editorconfig-vscode.png

在我 alt + shift + f 格式化以後能夠看到，VSCode 遵循了 editorconfig 的配置將代碼的縮進格式化成了 3 個空格。

我繼續在 IDEA 中打開這個項目後經過 ctrl + alt + l 格式化，意料之中也是格式化成了三個空格，我就不貼圖了，和上面同樣。因此，editorconfig 可讓咱們在使用不一樣的編輯器時格式化的保持風格一致。

有人可能會想，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 配置就沒什麼用了。

edittorconfig-prettier.png

說了那麼多，其實配置起來很是簡單，建議安裝 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 上測試，並不保證支持非 LTS 版本。

經過下面的 shell 命令生成 .nvmrc：

node --version > ./.nvmrc
複製代碼

.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/
複製代碼

測試一下其中幾個常見的源的丟包率，淘寶源一騎絕塵啊：

taobao-cnpm-registry.png

.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
複製代碼

咱們能夠在 淘寶 npm 鏡像 查看更多經常使用鏡像地址。

LICENSE

open source 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。其實 yarn 還有一個殺手級的特性 yarn workspace，用於管理 monorepos 的依賴，雖然這個項目不是 monorepos 結構，可是確實 說明一個問題 npm 在工程領域落後 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（註釋）的意思嘛。暫時添加如下內容：

{
    // stylelint 擴展自身的校驗就夠了
    "css.validate": false,
    "less.validate": false,
    "scss.validate": false,
    // 使用本地安裝的 TypeScript 替代 VSCode 內置的來提供智能提示
    "typescript.tsdk": "./node_modules/typescript/lib",
    // 指定哪些文件不參與搜索
    "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
    },
    // 配置 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"
    },
    "[yaml]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[markdown]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
}
複製代碼

咱們還能夠經過 .vscode/extensions.json 文件向用戶推薦一些擴展，在用戶打開該項目時若是有推薦的擴展未安裝 VSCode 就會提示用戶安裝，也能夠在擴展市場勾選過濾條件爲只顯示推薦的擴展查看：

// https://gist.github.com/tjx666/daa6317cf80ab5f467c50b2693527875
{
    "recommendations": [
        "editorconfig.editorconfig",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "stylelint.vscode-stylelint",
        "dsznajder.es7-react-js-snippets",
        "mrmlnc.vscode-scss",
        "yutengjing.view-github-repository",
        "yutengjing.open-in-external-app"
    ]
}
複製代碼

recommend extension

.travis.yml

我選擇使用最流行的開源 CI 工具 travis CI，在 github 上新建完倉庫後就能夠去 travis CI 官網，先同步 github 帳號信息，而後搜索激活新建的倉庫。後續我可能會考慮替換成 github actions，目前仍是先用 travis。

travis-ci.png

在項目根目錄新建 .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 渲染的圖片，咱們能夠在網站 shields.io 上找到各類各樣的 badge，平時逛 github 項目的時候看到喜歡的 badge 可用注意收藏一下。

badge-format.png

添加如下內容：

<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 屬性將標題，徽章和描述居中。

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 😁。對本文內容有疑問或者有什麼改進的地方歡迎經過 github issues 和發佈平臺的評論區交流。

本文爲原創內容，首發於我的博客，轉載請註明出處。

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程