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

建立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

克隆程式碼倉庫到本地

1. 開啟瀏覽器跳轉到我們剛剛建立的程式碼倉庫頁面，如: https://github.com/richardcuick/typescript。
2. 點選Code按鈕，複製HTTPS標籤下面的程式碼倉庫地址，如：https://github.com/richardcuick/typescript.git。
3. 開啟命令列，進入我們要建立程式碼倉庫的目錄，如@richardcuick
4. 使用命令git clone <程式碼倉庫地址>複製程式碼倉庫到本地
5. 進入複製的程式碼倉庫目錄，會看到如下檔案：

• .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可以通過命令列執行以下命令：

1. 清除Package快取：npm cache clean --force
2. 解除安裝Node.js：wmic product where caption="Node.js" call uninstall
3. 刪除相關目錄：

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。

1. 到NVM for Windows釋出頁面下載最新版本的nvm-setup.zip檔案，解壓縮，執行nvm-setup.exe進行安裝。

2. NVM for Windows安裝路徑預設為C:\Users\<User Name>\AppData\Roaming\nvm。

3. 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程式包，幫助開發人員增加提交程式碼前的步驟，如進行靜態程式碼檢查或格式化檔案。

1. 通過命令yarn add -D husky lint-staged安裝Husky和Lint-Staged
2. 如果你的程式包不是私有的，還要釋出到類似npmjs.com的註冊中心，請安裝pinst程式包。yarn add -D pinst
3. 執行命令yarn husky install啟用Git鉤子(Hooks)
4. 為了安裝後能自動啟用鉤子，編輯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"]
    } 
}

參考文件：

• Node.js
• 20 Useful wmic command examples in Windows | Cheat Sheet | CyberITHub
• Highlight Bash/shell code in Markdown files - Stack Overflow
• Set up NodeJS on native Windows | Microsoft Docs
• Common Issues · coreybutler/nvm-windows Wiki (github.com)
• TypeScript: How to set up TypeScript (typescriptlang.org)
• TypeScript: Bootstrapping tools for TypeScript projects (typescriptlang.org)
• npm vs npx — What’s the Difference? (freecodecamp.org)
• TypeScript: Documentation - What is a tsconfig.json (typescriptlang.org)
• Yarn vs NPM: A Comprehensive Comparison {7-Point Comparison} (phoenixnap.com)
• Installation | Yarn (yarnpkg.com)
• Getting Started with ESLint - ESLint - Pluggable JavaScript linter
• How to use ESLint with TypeScript | Khalil Stemmler
• Getting Started with ESLint - ESLint - Pluggable JavaScript linter
• How to use ESLint with TypeScript | Khalil Stemmler
• Install · Prettier
• eslint-config-prettier
• How to use ESLint with TypeScript
• Husky