前言

前面講完了 TypeScript，今天就來建立一個整合 TypeScript 的 Express 專案。

套件簡介

Express Generator TypeScript 是一個應用程式產生器,結合了 Express 框架與 TypeScript。

主要功能

• 快速建立 Express + TypeScript 專案
• 提供類似 express-generator 的功能
• 產生的應用程式使用 TypeScript 而非純 JavaScript
• 遵循 TypeScript 最佳實踐規範

解決的問題

Node.js 的挑戰

• Node.js 適合快速開發網頁專案
• 但常因缺乏型別安全而被質疑穩定性

TypeScript 的優勢

• 提供完整的型別安全機制
• 搭配 linter 後,程式碼更加穩健
• 甚至比某些靜態型別語言(如 Java)更可靠

與其他工具的比較

市面上雖有類似工具(如 express-generator-ts),但存在以下問題:

• 長期未維護更新
• 預裝許多非必要套件(如 ORM)

Express Generator TypeScript 的優勢

• 持續維護更新
• 極簡化配置
• 只安裝必要套件

核心特色

1. 極簡配置

因應單頁應用程式(SPA)的普及,本工具:

• 不預設配置視圖引擎
• 僅設定呼叫 API 和提供 index.html 所需的基本配置

2. 開發工具完整

內建所有開發所需工具:

• 開發模式執行(監聽檔案變更並自動重啟)
• 建置工具
• 測試框架
• 生產環境執行

3. 路徑別名設定

已預先設定路徑別名,無需額外安裝套件:

• 不需要 tsconfig-paths
• 不需要 module-alias

自訂路徑方式

• 更新 tsconfig.json 中的 paths
• 更新 preload.js 中的 _moduleAliases

安裝步驟

參考 express-generator-typescript 官方文件

1. 全域安裝(如果尚未安裝)

npm install -g express-generator-typescript

2. 快速建立專案

npx express-generator-typescript "專案名稱"

3. 執行測試

cd "專案名稱" && npm run dev

4. 解決跨平台問題

注意事項: 因作業系統差異,可能無法順利執行。建議先安裝 cross-env:

cross-env 是什麼?
一個跨平台的 Node.js 工具,用於在 npm script 中設定環境變數(如 NODE_ENV=production)。
讓 Windows (CMD/PowerShell) 與 Unix-like 系統 (macOS、Linux、WSL) 都能使用同一行指令成功執行,無需為不同作業系統維護多份腳本。

安裝 cross-env:

npm install --save-dev cross-env

修改 package.json:

{
  "scripts": {
    "build": "ts-node ./scripts/build.ts",
    "clean-install": "rm -rf ./node_modules && rm -r package-lock.json && npm i",
    "dev": "cross-env NODE_ENV=development ts-node ./src",
    "dev:hot": "nodemon --exec \"npm run dev\" --watch ./src --ext .ts",
    "lint": "eslint . --ext .ts",
    "lint:fix": "eslint . --ext .ts --fix",
    "start": "cross-env NODE_ENV=production node -r ./config.js ./dist",
    "test": "cross-env NODE_ENV=test vitest",
    "type-check": "tsc --noEmit"
  }
}

5. 啟動開發伺服器

執行以下指令應該就能順利運行:

npm run dev:hot

開啟瀏覽器訪問 http://localhost:3000/users,可以看到專案預設的畫面:

專案結構規劃

目標架構

初期目標是建立註冊登入系統,技術堆疊規劃如下:

• 資料庫: PostgreSQL + Supabase
• ORM: TypeORM
• 使用者驗證: JWT
• 第三方身份驗證: Passport.js
• 密碼處理: bcrypt(雜湊 + salt)

MVC 架構資料夾規劃

根據 MVC 架構,整理專案資料夾結構:

express-gen-ts/
├── app.ts                 # 主應用程式進入點
├── config/
│   └── database.ts        # TypeORM 資料庫配置
├── controllers/
│   ├── auth.ts           # 認證控制器
│   └── user.ts           # 用戶控制器
├── models/
│   ├── user.ts           # 用戶模型 (TypeORM Entity)
│   └── index.ts
├── routes/
│   └── auth.ts           # 認證路由
├── middlewares/          # 中介軟體
├── utils/                # 工具函數
├── types/                # TypeScript 類型定義
└── .env.example          # 環境變數範例

參考資源

• Express Generator TypeScript 官方文件