創建TypeScript程式碼模板(NVS+Yarn+ESLint+Prettier+Husky)

2022 年 4 月 1 日
筆記
Typescript & Node.js

創建TypeScript程式碼模板(NVS+Yarn+ESLint+Prettier+Husky)

Cui, Richard Chikun

本文筆者將帶你在Github程式碼倉庫創建TypeScript程式碼模板，並集成最新的程式碼開發工具，如：Node.js版本管理工具NVM for Windows、包管理器Yarn、靜態程式碼檢查工具ESLint、程式碼格式化工具Prettier、Git鉤子(Hook)工具Husky等。

安裝Visual Studio Code

在開始進行TypeScript開發之前，我們首先需要一個用於TypeScript開發的程式碼編輯器，類似的產品有VS Code、Atom、Sublime Text、Notepad++等等。我個人還是比較喜歡Visual Studio Code程式碼編輯器，有很強的程式碼編輯能力，支援豐富的插件功能。

可以通過以下步驟安裝VS Code:

打開瀏覽器，導航到Visual Studio Code – Code Editing. Redefined
下載最新的穩定版本(Stable)的VS Code編輯器
執行下載的安裝文件進入安裝導航，整個安裝過程簡單直接。
啟動VS Code編輯器，如果是在命令行狀態下，進入你要開發的工程或項目文件夾，通過命令code .就可以載入工程內的所有文件。

創建Github程式碼倉庫

首先我們通過Web頁面創建Github程式碼倉庫。

創建GitHub程式碼倉庫(Repository)並：

填寫倉庫名字(Repository Name)，如typescript
填寫描述(Description，可選項)，如TypeScript source template with modern tools
選擇訪問級別公開(Public)或私有(Private)，如選擇Public
勾選添加README.md說明文檔
勾選添加.gitignore忽略提交文件列表，並選擇Node模板
勾選添加許可，並選擇MIT許可(MIT License)。關於如何選擇許可類型可參考如何選擇開源許可證？ – 阮一峰的網路日誌，文中決策圖可以幫助你快速選擇合適的許可類型。

點擊創建倉庫(Create repository)之後，我們的Github程式碼倉庫就創建出來了。

安裝Git for Windows

接下來我們要安裝Git將程式碼倉庫克隆(clone)到本地進行開發工作，我們需要到Git for Windows網站，點擊頁面Download按鈕，下載最新的Git for Windows安裝程式，如Git-2.35.1.2-64-bit.exe。

雙擊下載的安裝程式執行安裝：

勾選Only show new options，並點擊Install按鈕。
取消勾選View Release Notes並點擊Finish按鈕結束安裝。

通過命令行命令git --version顯示安裝的Git版本並檢查Git是否成功安裝，成功安裝後控制台會返回Git的版本號，如：

git version 2.35.1.windows.2

克隆程式碼倉庫到本地

打開瀏覽器跳轉到我們剛剛創建的程式碼倉庫頁面，如: //github.com/richardcuick/typescript。
點擊Code按鈕，複製HTTPS標籤下面的程式碼倉庫地址，如：//github.com/richardcuick/typescript.git。
打開命令行，進入我們要創建程式碼倉庫的目錄，如@richardcuick
使用命令git clone <程式碼倉庫地址>複製程式碼倉庫到本地
進入複製的程式碼倉庫目錄，會看到如下文件：

.gitignore
LICENSE
README.md

安裝Node.js

TypeScript語言是運行於Node.js框架之上的，所以我們需要安裝Node.js。但是Node.js版本演變非常快，而且一般會具有LTS版本和最新特性的Current兩個版本，所以我們需要一個合適的Node版本管理器對Node.js的版本進行管理，Node版本管理器的作用就是可以在不同版本之間快速切換Node.js而不用頻繁、麻煩地卸載再安裝。

卸載已安裝的Node.js

為了安裝Node.js版本管理工具需要先將已安裝的Node.js卸載，如果你的電腦未安裝過Node.js可以跳過此步，直接瀏覽”安裝Node.js版本管理器NVM for Windows”。
想要完全乾凈地卸載Node.js可以通過命令行執行以下命令：

清除Package快取：npm cache clean --force
卸載Node.js：wmic product where caption="Node.js" call uninstall
刪除相關目錄：

rmdir /s /q %appdata%\npm
rmdir /s /q %appdata%\npm-cache
rmdir /s /q %programfiles%\Nodejs
rmdir /s /q %programfiles(x86)%\Nodejs
rmdir /s /q %homepath%\.npmrc
rmdir /s /q %homepath%\AppData\Local\Temp\npm-cache

安裝Node.js版本管理器NVM for Windows

Node的版本管理工具有NVM for Windows、nvs和Volta三個，使用最多的是NVM for Windows。

到NVM for Windows發布頁面下載最新版本的nvm-setup.zip文件，解壓縮，執行nvm-setup.exe進行安裝。
NVM for Windows安裝路徑默認為C:\Users\<User Name>\AppData\Roaming\nvm。
Node.js安裝路徑默認為C:\Program Files\nodejs。

打開控制台，執行nvm ls查看已安裝的Node.js版本命令檢查是否已成功安裝：

nvm ls

No installation recognized.

安裝LTS版本的Node.js

Node.js版本包括歷史版本、長期支援的LTS版本(這個版本是Node.js推薦大多用戶使用的，也是各大雲供應商在自己的雲服務中支援的版本)，以及當前最新特性版Current版本(這個版本會包含所有最新的功能，但多數情況下不受雲服務運行時支援)。

我們使用NVM for Windows可以通過兩個命令來查看和安裝Node.js版本：

nvm list available命令列出所有可用(可安裝)的Node.js版本。
nvm install <version>命令安裝對應版本的Node.js，其中version可以是latest或lts來安裝具有最新特性的版本或LTS版本。例如，當前LTS版本為16.14.2，推薦更多的用戶使用；而具有最新特性的當前版本為17.8.0。

我們推薦安裝LTS版本：

推薦使用命令nvm install lts安裝LTS版本的Node.js。
安裝後可使用nvm ls命令列出所有已經安裝的版本。
使用nvm use <version>命令指定Node.js版本，這裡的version不能使用latest或tls，必須是nvm ls命令列出的指定的版本號。如16.14.2。

P.S: 如果在執行nvm use <version>命令時遇到如下錯誤，建議檢查Node.js安裝路徑是否為空目錄，大部分時候是由於殘留了原來安裝的Node.js下面的文件和目錄，刪除即可。

exit 145: The directory is not empty
exit 32: The process cannot access the file because it is being used by another process.

通過以下命令行命令檢查Node.js和npm包管理器的版本來檢查Node.js是否已被正確安裝：

node --version
npm --version

激活yarn 2包管理器

對於16.10以上版本的Node.js已經通過Corepack內置了最新的yarn包管理器，yarn與npm一樣都是包管理器，用來管理程式包的安裝、卸載以及依賴關係，yarn從版本2開始對並行載入有了更好的支援，能快速進行包的更新，速度和效率上都遠勝於npm，所以我們建議使用yarn取代npm來管理我們的程式包。

其中支援yarn的Corepack默認已在16.10以上版本的Node.js安裝中，不過是禁用狀態，所以需要我們激活它：

corepack enable

然後我們就可以使用版本2的yarn初始化我們的TypeScript工程項目了：

yarn init -2

此命令會生成如下文件/目錄：

.editorconfig – 此文件定義了編輯器的縮進及文本轉行格式
.yarn目錄 – 此目錄用來保管安裝的程式包
package.json – 程式包的說明文件
.yarnrc.yml – 說明了程式包保管路徑
yarn.lock

安裝TypeScript

本地開發安裝TypeScript包：yarn add -D typescript
使用命令yarn tsc -v檢查安裝TypeScript的版本。
創建src目錄：md src
進入src目錄：cd src
創建index.ts，內容如下：

let message: string = 'Hello, World!'; 
console.log(message);

運行TypeScript命令行：npm tsc index.ts ，生成index.js文件。
運行node index.js，執行Javascript文件。
yarn tsc --init初始化tsconfig.json文件，默認配置為：

{
    "compilerOptions": {
          "target": "es2016",
          "module": "commonjs",
          "strict": true,
          "esModuleInterop": true,
          "skipLibCheck": true,
          "forceConsistentCasingInFileNames": true
    }
}

參考標準項目目錄結構如下：

project folder\
|---- dist\
|---- src\
|---- test\
|---- package.json
|---- tsconfig.json

修改tsconfig，更新如下項目：

{
    "compilerOptions": {
        "rootDir": "src",
        "sourceMap": true,
        "outDir": "dist",
    },
"include": ["src/**/*"],
"exclude": [".yarn", "**/*.spec.ts"]
}

配置完，保存並運行yarn tsc，就可以看到自動生成了dist目錄，並且在目錄中生成了index.js和index.js.map文件。

安裝ESLint

ESLint是靜態程式碼檢查工具，配合TypeScript使用可以幫助檢查TypeScript的語法和程式碼風格。

添加ESLint到當前工程，yarn add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin。

通過命令行命令code .eslintrc或打開VS Code創建.eslintrc文件，增加內容如下：

{
    "root": true,
    "parser": "@typescript-eslint/parser",
    "plugins": [
        "@typescript-eslint"
    ],
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/eslint-recommended",
        "plugin:@typescript-eslint/recommended"
    ]
 }

通過命令行命令code .eslintignore或打開VS Code創建.eslintignore文件，增加內容如下：

# Ignore artifacts: 
.yarn
dist

運行命令yarn eslint . --ext .ts執行程式碼靜態檢查，運行命令yarn eslint . --ext .ts --fix執行程式碼修復。

通過命令npm set-script lint "eslint . --ext .ts"向package.json添加lint(靜態程式碼檢查)腳本：

{
    "scripts": {
        "lint": "eslint . --ext .ts",
    }
}

添加腳本後，可直接使用yarn lint命令進行靜態程式碼檢查。

安裝Prettier

Prettier是優化程式碼格式的工具，可優化JavaScript、TypeScript、JSON等程式碼及配置文件。

使用命令yarn add -D --exact prettier安裝Prettier。
創建文件.prettierrc.json，內容如下：

{}

創建文件.prettierignore，內容如下：

# Ignore artifacts: 
dist 
coverage

執行命令優化文件格式：yarn prettier --write .
執行命令檢查文件格式：yarn prettier --check .

命令行輸出如下：

C:\@richardcuick\ts>yarn prettier --write .
yarn run v1.22.18
$ C:\@richardcuick\ts\node_modules\.bin\prettier --write .
.eslintrc.json 111ms
.prettierrc.json 2ms
dist\index.js 9ms
package-lock.json 98ms
package.json 21ms
src\index.ts 274ms
tsconfig.json 9ms
Done in 1.04s.

C:\@richardcuick\ts>yarn prettier --check .
yarn run v1.22.18
$ C:\@richardcuick\ts\node_modules\.bin\prettier --check .
Checking formatting...
All matched files use Prettier code style!
Done in 0.69s.

C:\@richardcuick\ts>

因為同時安裝了ESLint和Prettier會導致靜態程式碼檢查和格式化之間的一些衝突，可以通過安裝eslint-config-prettier程式包解決類似衝突。

執行yarn add -D eslint-config-prettier安裝此程式包
運行code .eslintrc命令或編輯.eslintrc文件添加”prettier”到extends集合，如下：

{
    "extends": [
        "some-other-config-you-use",
        "prettier"
    ]
}

安裝Husky

Husky是Git hooks程式包，幫助開發人員增加提交程式碼前的步驟，如進行靜態程式碼檢查或格式化文件。

通過命令yarn add -D husky lint-staged安裝Husky和Lint-Staged
如果你的程式包不是私有的，還要發布到類似npmjs.com的註冊中心，請安裝pinst程式包。yarn add -D pinst
執行命令yarn husky install激活Git鉤子(Hooks)
為了安裝後能自動激活鉤子，編輯package.json文件，如下：

// package.json 
{ 
    "private": true, // ← your package is private, you only need postinstall 
    "scripts": { 
        "postinstall": "husky install" 
    } 
}

但是如果你的包不是私有的，你要發布到註冊中心如npmjs.com，那麼你需要使用pinst禁用postinstall。否則，postinstall將會在別人安裝你的程式包的時候運行並報錯。

// package.json 
{ 
    "private": false, // ← your package is public 
    "scripts": { 
        "postinstall": "husky install", 
        "prepack": "pinst --disable", 
        "postpack": "pinst --enable" 
    } 
}

yarn husky add .husky/pre-commit "yarn lint-staged"

編輯package.json文件如下，在提交程式碼前進行靜態程式碼檢查和格式優化：

{ 
    "lint-staged": { 
        "src\\**\\*.ts": ["eslint", "prettier --write"]
    } 
}

Tags: Typescript & Node.js