編碼慣例
程式碼組織
- 單一職責:每個原始檔都應有明確、專注的範圍/目的
- 拆分大型檔案:當檔案變得龐大或處理過多關注點時,將其拆分
- 型別分離:總是將型別與介面分離到
types.ts或types/*.ts中 - 常數提取:將常數移到專屬的
constants.ts檔案
執行環境
- 偏好同位程式碼:盡可能撰寫無關執行環境的程式碼,使其在 Node、瀏覽器與 Worker 中皆可運作
- 明確的環境標示:當程式碼是特定環境專用時,在檔案頂部加入註解:
// @env node
// @env browser
TypeScript
- 明確的回傳型別:盡可能明確宣告回傳型別
- 避免複雜的行內型別:將複雜型別提取到專屬的
type或interface宣告中
註解
- 避免不必要的註解:程式碼應能自我解釋
- 說明「為什麼」而非「怎麼做」:註解應描述推理過程或意圖,而非程式碼在做什麼
測試(Vitest)
- 測試檔案:
foo.ts→foo.test.ts(同一目錄) - 使用
describe/itAPI(非test) - 使用
toMatchSnapshot處理複雜輸出 - 使用
toMatchFileSnapshot搭配明確路徑處理語言專用快照
工具選擇
@antfu/ni 指令
| 指令 | 說明 |
|---|---|
ni | 安裝相依套件 |
ni <pkg> / ni -D <pkg> | 新增相依套件 / 開發相依套件 |
nr <script> | 執行腳本 |
nu | 升級相依套件 |
nun <pkg> | 移除相依套件 |
nci | 乾淨安裝(pnpm i --frozen-lockfile) |
nlx <pkg> | 執行套件(npx) |
TypeScript 設定
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true
}
}
ESLint 設定
// eslint.config.mjs
import antfu from '@antfu/eslint-config'
export default antfu()
完成任務時,請執行 pnpm run lint --fix 來格式化程式碼並修正程式碼風格。
詳細配置選項請參閱:antfu-eslint-config
Git Hooks
{
"simple-git-hooks": {
"pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
},
"lint-staged": { "*": "eslint --fix" },
"scripts": {
"prepare": "npx simple-git-hooks"
}
}
pnpm Catalogs
在 pnpm-workspace.yaml 中使用具名目錄(catalogs)來管理版本:
| 目錄 | 用途 |
|---|---|
prod | 生產相依套件 |
inlined | 建置工具內嵌的相依套件 |
dev | 開發工具(linter、bundler、測試) |
frontend | 前端函式庫 |
避免使用預設目錄。目錄名稱可根據專案需求調整。
參考資料
| 主題 | 說明 | 參考文件 |
|---|---|---|
| ESLint 設定 | 框架支援、格式化工具、規則覆寫、VS Code 設定 | antfu-eslint-config |
| 專案設定 | .gitignore、GitHub Actions、VS Code 擴充功能 | setting-up |
| 應用程式開發 | Vue/Nuxt/UnoCSS 慣例與模式 | app-development |
| 函式庫開發 | tsdown 打包、純 ESM 發布 | library-development |
| Monorepo | pnpm workspaces、集中式別名、Turborepo | monorepo |