前端套件”udi-pacakge”開發流程:

概述

前端專案共用套件 udi-package 開發規範 目的:集中管理跨專案Component、Utils Function

---test

架構說明

編譯工具分工

• Rollup: 編譯套件輸出為標準 npm 包格式
• Webpack: 編譯 sandbox 本地開發環境,提供熱更新與套件獨立的即時預覽

開發模式

1. 正常開發模式: 使用 npm 官方發布的套件版本
2. Link 開發模式: 使用本地 udi-package 進行即時開發

資料夾結構

project-root/
├── frontend-project/          # 前端專案
│   ├── node_modules/
│   ├── package.json
│   └── .git/
│       └── hooks/
│           └── pre-push      # Git hook 防護
└── udi-package/              # 共用套件 (與前端專案同層)
    ├── src/
    ├── dist/                 # Rollup 編譯輸出
    └── package.json

⚠️ 重要: udi-package 必須與前端專案放在同一層級,因為 Docker volume 需要使用固定路徑進行映射。

前置作業

1. 資料夾配置

將 udi-package 放置在與前端專案相同的目錄層級。 (首次clone下來必須執行 npm install & 若要使用npm link則需要先執行npm run build打包dist檔案給前端專案抓取)

2. 設置 Git Hook 防護

在前端專案中執行以下命令:

nano .git/hooks/pre-push

貼上以下內容:

#!/bin/bash

# 檢查 @udi-organization/udi-package 是否為 symlink (npm link)
PACKAGE_PATH="node_modules/@udi-organization/udi-package"

if [ -L "$PACKAGE_PATH" ]; then
    echo "❌ 錯誤: 檢測到使用 npm link"
    echo ""
    echo "目前 @udi-organization/udi-package 是使用本地 link"
    echo "請先執行以下命令切換回正式版本:"
    echo ""
    echo "  npm run get-udi-o"
    echo ""
    echo "或手動執行:"
    echo "  npm uninstall @udi-organization/udi-package --legacy-peer"
    echo "  npm install @udi-organization/udi-package@latest --legacy-peer"
    echo ""
    exit 1
fi

# 檢查通過
echo "✓ 檢查通過: 未使用本地 link"
exit 0

儲存並設置執行權限:

# Ctrl+O (儲存) → Enter → Ctrl+X (退出)
chmod +x .git/hooks/pre-push

3. NPM 組織設定

建立並加入組織

1. 建立個人 npm 帳號

2. 由管理員邀請加入 @udi-organization 組織

3. 執行登入:

   npm login
      

   會自動開啟瀏覽器完成登入

4. 確認登入狀態:

   npm whoami
      

NPM Scripts 說明

前端專案指令

{
  "scripts": {
    // 正常開發模式 自動取得最新版本udi-package - 使用 npm 官方套件
    "dev": "npm i @udi-organization/udi-package@latest --legacy-peer && NODE_ENV=development webpack-dev-server --progress  --hot --mode=development --host=0.0.0.0",

    // Link 開發模式 - 使用本地 udi-package
    "dev-udi": "npm uninstall @udi-organization/udi-package --legacy-peer && cd ../udi-package && sudo npm link && cd ../build && npm link @udi-organization/udi-package --legacy-peer && NODE_ENV=development webpack-dev-server --progress  --hot --mode=development --host=0.0.0.0",

    // 切換回正常模式 (不啟動專案) 也可用於取得最新版本udi-package
    "get-udi-o": "npm i @udi-organization/udi-package@latest --legacy-peer",
  }
}

udi-package 套件指令

{
  "scripts": {
    // 監聽模式 - 自動編譯變更
    "watch": "rollup -c --watch",

    // 單次編譯
    "build": "rollup -c",

    // 發布新版本（已改為 GitLab CI 自動處理，一般不需手動執行）
    "release": "自動更新版本號並發布至 npm"
  }
}

開發流程

情境一: 不需修改 udi-package

# 直接啟動專案
npm run dev

情境二: 需要開發 udi-package

步驟 1: 啟動套件監聽

在 udi-package 目錄執行:

npm run watch
# 或單次編譯
npm run build

步驟 2: 啟動 Link 開發模式

在前端專案目錄執行:

npm run dev-udi

步驟 3: 開發與測試

• 修改 udi-package/src 中的程式碼
• Rollup 會自動編譯至 dist/ 目錄
• 前端專案透過 link 即時取得更新

步驟 4: 發布新版本

版本發布已改為由 GitLab CI 自動化處理，不需要手動執行 npm run release。

發布流程:

1. 確保所有變更已 commit
2. 推送到 GitLab
3. GitLab CI 會自動執行測試、建置和發布

# 在 udi-package 目錄
git add .
git commit -m "feat: 新功能說明"
git push origin "new feature branch"
# GitLab CI 會自動處理發布流程

查看發布狀態: 在 GitLab 專案的 CI/CD > Pipelines 頁面查看自動發布的執行狀態。

手動發布（僅緊急情況）:

npm run release  # 一般情況請勿使用，優先使用 GitLab CI 自動發布

Git 推送流程

完整推送步驟

1. 建立 Feature Branch

   git checkout -b feature/your-feature-name
      

2. 持續開發與提交

   git add .
   git commit -m "feat: 功能描述"
   git push origin feature/your-feature-name
      

3. 推送前切換回正常模式

   # 方法一: 只切換不啟動
   npm run get-udi-o
      
   # 方法二: 切換並驗證專案
   npm run dev
      

4. 驗證專案正常運作

   • 確認專案可正常啟動
   • 確認功能運作正常
   • 確認 package.json 包含正式的套件依賴

5. 推送到 GitLab

   git push origin feature/your-feature-name
      

   Git hook 會自動檢查是否為 link 模式,防止錯誤推送

6. 通過 Pipeline 後合併

   • 確認 GitLab CI/CD Pipeline 全部通過
   • 提交 Merge Request 至 dev 分支
   • Code Review 通過後合併

常見問題處理

Q1: 推送時出現 "檢測到使用 npm link" 錯誤

原因: 目前處於 link 開發模式

解決:

npm run get-udi-o
# 或
npm run dev  # 切換並驗證專案

Q2: udi-package 修改後前端專案沒有更新

檢查項目:

1. 確認 udi-package 目錄是否執行 npm run watch
2. 確認前端專案是否使用 npm run dev-udi 啟動
3. 檢查編譯是否有錯誤訊息

Q3: npm link 權限問題

解決: 使用 sudo 執行 link 指令

cd ../udi-package
sudo npm link

Q4: 發布失敗 - 未登入或權限不足

解決:

npm login
npm whoami  # 確認登入狀態

快速參考

常用指令速查

| 情境 | 指令 | | --- | --- | | 正常開發 | npm run dev | | 開發套件 | npm run dev-udi | | 切換回正常模式 | npm run get-udi-o | | 套件監聽編譯 | npm run watch (在 udi-package) | | 發布新版本 | 由 GitLab CI 自動處理 | | 檢查登入狀態 | npm whoami |

檢查清單

開發前

• [ ] udi-package 與專案在同層目錄
• [ ] Git hook 已設置
• [ ] npm 已登入正確組織

推送前

• [ ] 切換回正常模式 (npm run get-udi-o)
• [ ] 專案可正常運作
• [ ] 所有變更已 commit

發布套件前

• [ ] 所有變更已 commit 並推送到 GitLab
• [ ] 確認 GitLab CI Pipeline 執行成功
• [ ] GitLab CI 會自動處理版本發布