跳至主要内容

yalc 本地開發工作流程

本文檔說明如何使用 yalc 進行框架的本地開發與測試。

何時使用 yalc​

yalc 僅用於特殊測試情境，正常開發應使用私有 registry。

情境使用工具
正常開發私有 registry（npm install @appfuse/appfuse-web）
測試未發布的框架變更yalc
CI/CD私有 registry

使用 yalc 的典型場景​

  1. 框架新增功能，需要在參考實作中驗證，但尚未準備發布
  2. 修復框架 bug，需要快速驗證修復是否有效
  3. 重大重構前，在參考實作中進行整合測試
工具行為優點缺點
npm linkSymlink 到原始碼目錄即時更新React hooks 多實例問題
file: 協議Symlink簡單同上
yalc複製 dist/ 到 .yalc模擬真實 npm需手動推送更新

yalc 的優勢​

  1. 複製實際檔案，不是 symlink → 更接近真實使用
  2. 自動處理依賴解析，避免 React 多實例問題
  3. 簡單的發布流程，不需要每次都發布到 registry
  4. 支援多專案同步更新

安裝​

npm install -g yalc

基本工作流程​

1. 發布框架（appfuse-web）​

cd /path/to/appfuse-web

# 編譯框架
npm run build

# 發布到本地 yalc store
yalc publish

# 輸出：@appfuse/appfuse-web@0.0.9 published in store.

2. 使用框架（app-web-mockup / app-web）​

cd /path/to/app-web-mockup  # 或 app-web

# 添加框架依賴
yalc add @appfuse/appfuse-web

# 安裝依賴
npm install

執行後會：

  • 在專案根目錄建立 .yalc/ 目錄
  • 在專案根目錄建立 yalc.lock 檔案
  • 修改 package.json 的依賴為 "@appfuse/appfuse-web": "file:.yalc/@appfuse/appfuse-web"

3. 更新框架​

當框架有更新時：

cd /path/to/appfuse-web

# 編譯框架
npm run build

# 推送更新到所有使用方
yalc push

# 輸出：
# @appfuse/appfuse-web@0.0.9 published in store.
# Pushing @appfuse/appfuse-web@0.0.9 in /path/to/app-web-mockup
# Pushing @appfuse/appfuse-web@0.0.9 in /path/to/app-web

yalc push 會自動更新所有使用 yalc add 的專案。

進階用法​

查看已發布的套件​

yalc installations show @appfuse/appfuse-web

移除 yalc 依賴（切換到 npm）​

當準備發布到 npm 時：

cd /path/to/app-web

# 移除 yalc 依賴
yalc remove @appfuse/appfuse-web

# 安裝 npm 版本
npm install @appfuse/appfuse-web

清理 yalc store​

# 清理特定套件
yalc installations clean @appfuse/appfuse-web

# 清理所有
yalc installations clean

專案配置​

.gitignore​

將以下內容加入 .gitignore：

# yalc
.yalc/
yalc.lock

package.json（使用 yalc 後的樣子）​

{
  "dependencies": {
    "@appfuse/appfuse-web": "file:.yalc/@appfuse/appfuse-web"
  }
}

常見問題​

Q: yalc push 後沒有更新？​

確保：

  1. 先執行 npm run build 編譯框架
  2. 使用方執行 npm install 重新安裝依賴

Q: TypeScript 類型沒有更新？​

重啟 IDE 或 TypeScript Server：

  • VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"

Q: React hooks 報錯「Invalid hook call」？​

確認使用 yalc 而非 npm link。如果問題持續，檢查 node_modules 中是否有多個 React 版本。

Q: 如何同時開發框架和應用？​

推薦工作流程：

  1. 開啟兩個終端機
  2. 終端機 1：框架開發 
    cd appfuse-web
    npm run dev  # 或 watch mode
  3. 終端機 2：應用開發 
    cd app-web-mockup
    npm run dev
  4. 框架修改後： 
    cd appfuse-web
    npm run build && yalc push
  5. 應用會自動重新載入（如果有 HMR）

CI/CD 注意事項​

本地開發 vs CI/CD​

環境依賴來源
本地開發yalc（.yalc/ 目錄）
CI/CDnpm（npm registry）

CI/CD 配置​

在 CI/CD 中，應使用 npm 版本而非 yalc：

# .github/workflows/ci.yml
steps:
  - name: Install dependencies
    run: |
      # 確保使用 npm 版本
      yalc remove @appfuse/appfuse-web || true
      npm install

或在 package.json 中使用條件依賴：

{
  "dependencies": {
    "@appfuse/appfuse-web": "^0.0.9"
  }
}

發布前記得將 yalc 依賴改回 npm 版本。

參考資源​