antfu

編碼實務

程式碼組織

• 單一職責：每個原始檔應有明確、聚焦的範圍/目的
• 拆分大型檔案：當檔案過大或處理太多關注點時，將其拆分
• 型別分離：一律將型別與介面分離至 types.ts 或 types/*.ts
• 常數提取：將常數移至專屬的 constants.ts 檔案

執行環境

• 偏好同構程式碼：盡可能撰寫與執行環境無關的程式碼，使其能在 Node、瀏覽器與 Worker 中運作
• 明確標示執行環境：當程式碼限定特定環境時，在檔案頂端加上註解：

// @env node
// @env browser

TypeScript

• 明確回傳型別：盡可能明確宣告回傳型別
• 避免複雜的內聯型別：將複雜型別提取為專屬的 type 或 interface 宣告

明確性

偏好明確、可追蹤的程式碼，而非隱含的「魔法」。閱讀者（人類或代理）應能在不執行工具的情況下，追蹤每個名稱的來源。

• 明確匯入：偏好明確的 import 陳述式。避免自動匯入——當框架提供此功能時（例如 Nuxt/Nitro），在新專案中將其關閉（參見 app-development）。
• 預設不使用路徑別名：使用相對匯入（./foo、../bar）。僅在專案中已設定路徑別名（@/、~/、#imports 等）時才使用，不要為全新程式碼引入新的別名。

註解

• 避免不必要的註解：程式碼應能自我解釋
• 解釋「為什麼」而非「怎麼做」：註解應描述原因或意圖，而非程式碼做了什麼

測試（Vitest）

• 測試檔案：foo.ts → foo.test.ts（相同目錄）
• 使用 describe/it API（而非 test）
• 對複雜輸出使用 toMatchSnapshot
• 對語言特定的快照使用 toMatchFileSnapshot 並指定明確路徑

---

工具選擇

@antfu/ni 指令

指令	說明
ni	安裝依賴
ni <pkg> / ni -D <pkg>	新增依賴 / 開發依賴
nr <script>	執行腳本
nu	升級依賴
nun <pkg>	移除依賴
nci	乾淨安裝（pnpm i --frozen-lockfile）
nlx <pkg>	執行套件（npx）

檢查 npm 套件版本

使用 fast-npm-meta 查詢套件的最新版本——它會查詢一個小型中繼資料端點，而非下載完整的 registry 負載（每個套件可能達數 MB）。

nlx fast-npm-meta version vite              # 7.3.1
nlx fast-npm-meta version "nuxt@^3.5"       # 3.5.22 — 範圍感知
nlx fast-npm-meta version vite nuxt vue     # 一次查詢多個
nlx fast-npm-meta version vite --json       # 輸出 JSON 供腳本使用
nlx fast-npm-meta full vite                 # 完整版本列表 + dist-tags

當你只需要最新版本時，優先使用此工具而非 npm view <pkg> version，也勝過直接從 registry 讀取 package.json。

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 中使用具名目錄來管理版本：

目錄	用途
prod	正式環境依賴
inlined	打包器內聯依賴
dev	開發工具（linter、bundler、測試）
frontend	前端函式庫

避免使用預設目錄。目錄名稱可依專案需求調整。

---

參考資料

主題	說明	參考文件
ESLint 設定	框架支援、格式化工具、規則覆寫、VS Code 設定	antfu-eslint-config
專案設定	.gitignore、GitHub Actions、VS Code 擴充功能	setting-up
應用程式開發	Vue/Nuxt/UnoCSS 慣例、自動匯入控制、Storybook 元件測試	app-development
函式庫開發	tsdown 打包、純 ESM 發布	library-development
Monorepo	pnpm workspaces、集中式別名、Turborepo	monorepo