@udi-organization/udi-package

UDI 共用元件套件，供各前端專案（client）使用。

目錄

• 元件使用指南
  • UdiTable
  • [useUdiTableSync（兩表格同步）](#useuditable sync兩表格同步)
  • useUdiTableSyncMutipleTable（多表格同步）
• 專案結構
• 前置作業
• 開發流程
  • Link 模式（本地即時開發）
  • Release 模式（使用 npm 正式版）
• 版本資訊
• 版本發布
  • 測試版（Alpha / Beta）
  • 正式版（自動 CI/CD）
• Pre-push Hook 說明
• CI/CD 設定
  • npm Automation Token
  • GitLab CI/CD Variables

元件使用指南

安裝與引入

npm install @udi-organization/udi-package --legacy-peer-deps

import { UdiTable, useUdiTableSync, useUdiTableSyncMutipleTable } from '@udi-organization/udi-package';

專案結構

udi-package/          ← 套件端（本專案）
web-frontend/         ← 客戶端（前端專案）

重要：udi-package 需與前端專案放在同一層目錄，Docker volume 映射時會依此固定路徑抓取。

前置作業

1. 加入 npm 開發組織

   1. 使用公司 email 建立 npm 帳號：https://www.npmjs.com
   2. 請管理員邀請加入組織 @udi-organization
   3. 執行登入並確認身份：

      npm login
      npm whoami

2. 設定 CI/CD Token（團隊中只需一人設定，詳見下方說明）

開發流程

Link 模式（本地即時開發）

在 udi-package 有持續變動時使用，client 端會直接讀取本地 dist/ 資料夾。

套件端（udi-package）：

# 持續監聽並自動編譯（推薦）
npm run watch

# 或單次編譯
npm run build

客戶端（web-frontend）：

# 切換至 link 模式並啟動開發伺服器
npm run dev-udi

# 只切換至 link 模式，不啟動開發伺服器
npm run dev-udi-o

dev-udi 執行流程：

1. 解除安裝 npm 上的 @udi-organization/udi-package
2. 在 /udi-package 執行 sudo npm link（建立全域連結）
3. 在 /build 執行 npm link @udi-organization/udi-package（套用本地連結）
4. 啟動 webpack dev server

注意：link 模式會將 @udi-organization/udi-package 從 package.json 中移除，改用本地路徑作為依賴。git push 前必須先切換回 release 模式。

Release 模式（使用 npm 正式版）

套件開發完畢、測試通過後，client 端切換回從 npm 取得套件。

客戶端（web-frontend）：

# 安裝最新版並啟動開發伺服器
npm run get-udi

# 只安裝最新版，不啟動開發伺服器
npm run get-udi-o

# 安裝指定版本（測試版或特定版本）
npm install @udi-organization/udi-package@<版號> --legacy-peer-deps

版本資訊

當前版本

於 package.json 查看目前版號：

node -p "require('./package.json').version"

或至 npm 查詢已發布的最新版本：

npm view @udi-organization/udi-package version          # 最新正式版
npm view @udi-organization/udi-package dist-tags        # 所有 tag（latest / alpha / beta）
npm view @udi-organization/udi-package versions --json  # 完整版本列表

版號格式（SemVer）

本套件遵循 語意化版本（Semantic Versioning）：

major.minor.patch[-prerelease.N]

範例：
  1.0.76              正式版
  1.0.77-alpha.1      alpha 測試版第 1 次
  1.0.77-alpha.2      alpha 測試版第 2 次（重複執行 npm run alpha）
  1.0.77-beta.1       beta 測試版第 1 次

版號遞增規則

| 版號類型 | 觸發方式 | 範例 | |----------|----------|------| | patch（修補） | 推送至 dev 分支時由 pre-push hook 自動遞增 | 1.0.76 → 1.0.77 | | minor（次版本） | 手動執行 npm run release-minor | 1.0.76 → 1.1.0 | | major（主版本） | 手動執行 npm run release-major | 1.0.76 → 2.0.0 | | alpha（測試版） | 手動執行 npm run alpha | 1.0.76 → 1.0.77-alpha.1 | | beta（測試版） | 手動執行 npm run beta | 1.0.76 → 1.0.77-beta.1 |

預發布版本（alpha/beta）推送至 GitLab dev 分支前，pre-push hook 會自動切回正式版號。

版本發布

測試版（Alpha / Beta）

開發中需要讓 client 端測試時，發布測試版本至 npm。測試版無須推送至 GitLab。

# 步驟 1：產生測試版版號（可重複執行以遞增版號）
npm run alpha
# 範例：1.0.75 → 1.0.76-alpha.1 → 1.0.76-alpha.2

# 步驟 2：編譯並推送至 npm
npm run alpha:publish

Beta 版同理：

npm run beta
npm run beta:publish

發布後，於 package.json 確認版號，並通知 client 端執行：

npm install @udi-organization/udi-package@<版號> --legacy-peer-deps

正式版（自動 CI/CD）

確認測試通過後，推送至 GitLab dev 分支即可自動觸發 CI/CD 流程。

流程如下：

1. 執行 git push（推送到 dev 分支）
2. Pre-push hook 自動執行測試，並遞增 patch 版號後推送
3. GitLab CI/CD 自動執行：
   • 安裝依賴 → 執行測試 → 管理版號 → 編譯套件 → 發布至 npm

注意：若當前版號為 alpha/beta 預發布版本，pre-push hook 會先自動切回正式版號並合併至最近一次 commit，然後要求重新執行 git push。

Pre-push Hook 說明

Push 到 dev 分支時，husky pre-push hook 會自動執行以下動作：

| 情境 | 行為 | |------|------| | 一般 commit 推送到 dev | 執行測試 → 自動遞增 patch 版號 → 推送版號 commit → 觸發 CI/CD | | 推送到非 dev 分支 | 只執行測試，不自動打版號 | | 版號為 alpha/beta 時推送 | 自動切回正式版、合併至最近 commit，提示重新 push |

Hook 完成推送後會以 exit 1 結束，終端機會出現 error 訊息，這是預期行為，實際推送已成功完成，可忽略此錯誤。

CI/CD 設定

團隊中只需一人設定，完成後所有成員皆可享有自動發布功能。

npm Automation Token

1. 登入 https://www.npmjs.com
2. 右上角頭像 → Access Tokens → Generate New Token
3. 選擇 Classic Token → 選擇 Automation 類型
4. 複製產生的 token（格式：npm_xxxxxxxxxxxx）

   ⚠️ 離開頁面後無法再次查看，請立即複製

GitLab CI/CD Variables

需設定兩個 Variables：NPM_TOKEN 和 CI_PUSH_TOKEN

設定 NPM_TOKEN

1. 進入 GitLab 專案 udi / udi-package

2. 左側選單 → Settings → CI/CD → Variables → Add variable

3. 填入：

   | 欄位 | 值 | |------|----| | Key | NPM_TOKEN | | Value | 上一步複製的 npm_xxxx... | | Flags | ✅ Mask variable、✅ Protect variable |

設定 CI_PUSH_TOKEN（GitLab Personal Access Token）

1. GitLab 右上角頭像 → Edit Profile → Access Tokens → Add new token

2. 填入：

   | 欄位 | 值 | |------|----| | Token name | CI Push Token | | Expiration date | 設定一年後 | | Scopes | ✅ write_repository |

3. 複製產生的 token（格式：glpat-xxxxxxxxxxxxxxxxxxxx）

4. 回到專案 Settings → CI/CD → Variables → Add variable，填入：

   | 欄位 | 值 | |------|----| | Key | CI_PUSH_TOKEN | | Value | 上方複製的 glpat-xxxx... | | Flags | ✅ Mask variable、✅ Protect variable |

Scripts 速查

套件端（udi-package）

| 指令 | 說明 | |------|------| | npm run dev | 啟動本地 webpack dev server（元件開發用沙箱） | | npm run build | 單次編譯，輸出至 dist/ | | npm run watch | 持續監聽並自動編譯 | | npm run test | 執行 Jest 單元測試 | | npm run alpha | 產生 alpha 測試版版號 | | npm run alpha:publish | 編譯並推送 alpha 版至 npm | | npm run beta | 產生 beta 測試版版號 | | npm run beta:publish | 編譯並推送 beta 版至 npm |

客戶端（web-frontend）

| 指令 | 說明 | |------|------| | npm run dev | 一般開發模式（使用 npm 版套件） | | npm run dev-udi | Link 模式：連結本地套件並啟動 dev server | | npm run dev-udi-o | Link 模式：只連結本地套件，不啟動 dev server | | npm run get-udi | 從 npm 安裝最新版套件並啟動 dev server | | npm run get-udi-o | 從 npm 安裝最新版套件（不啟動 dev server） |