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

崔馳坤Richard 發表於 2022-04-01

建立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 WindowsnvsVolta三個,使用最多的是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"]
    } 
}

參考文件:

相關文章