Rush Stack商店部落格活動
跳到主要內容

將專案新增至儲存庫

這是從「設定新的儲存庫」開始的教學課程的繼續。(若要查看根據這些步驟完整運作的範例，請查看 GitHub 上的 rush-example 儲存庫。)

步驟 4：新增您的第一個專案​

我們建議一次新增並驗證一個專案，而不是嘗試一次將所有專案新增至 rush.json。請回想一下，您的專案會形成一個相依性圖表，因此請從「葉」專案 (不相依於儲存庫中任何其他專案) 開始，然後反向進行。如果您遇到任何錯誤，這種方法可以更容易地瞭解並調查它們。如果您單獨提交每個新增的專案，這也會讓您的 Git 歷史記錄更容易讓其他人理解。

對於此範例，我們先從新增假設的 my-toolchain 專案開始，這個專案是建置其他所有專案所必需的。由於我們將符合「類別資料夾」模型 (在 rush.json 註解中說明)，我們會將此專案移至「工具」類別資料夾下。最終，我們計畫將其他 NodeJS 工具套件放入「工具」資料夾

~/my-repo$ mkdir tools
~/my-repo$ cd tools
~/my-repo/tools$ cp -R ~/my-toolchain/ .
~/my-repo/tools$ cd my-toolchain

接下來，我們需要刪除在單一儲存庫中集中協調的專案特定檔案

  • 刪除本機縮排檔，因為它會被 Rush 的通用縮排檔取代。
  • 考慮刪除專案的 .npmrc 檔案，因為 Rush 作業一律會使用 common/config/rush/.npmrc
  • 考慮刪除專案的 Git 設定檔，除非它們包含真正特定於該專案的規則
~/my-repo/tools/my-toolchain$ rm -f shrinkwrap.yaml npm-shrinkwrap.json package-lock.json yarn.lock
~/my-repo/tools/my-toolchain$ rm -f .npmrc          # (if it makes sense)
~/my-repo/tools/my-toolchain$ rm -f .gitattributes  # (if it makes sense)
~/my-repo/tools/my-toolchain$ rm -f .gitignore      # (if it makes sense)

關於「縮排檔」的詳細資訊

根據您的套件管理員，縮排檔可能會稱為 shrinkwrap.yaml、npm-shrinkwrap.json、package-lock.json 或 yarn.lock。(某些套件管理員使用「鎖定檔」一詞，儘管它與檔案鎖定無關。在本文件中，我們會將其泛稱為「縮排檔」，因為我們不知道您會選擇哪一個套件管理員。)

通常，套件管理員會在每個專案資料夾中建立縮排檔，但在 Rush 儲存庫中，有一個單一的「通用」縮排檔，描述整個儲存庫。它會儲存在 common/config/rush 資料夾中，而且應該提交至 Git。將所有相依性資訊整合到單一縮排檔中，對於減少合併衝突、檢閱差異以及提高安裝速度有許多好處。

將新的專案檔案提交至 Git

~/my-repo/tools/my-toolchain$ cd ../..
~/my-repo$ git add .
~/my-repo$ git commit -m "Adding my-toolchain"

步驟 5：執行您的第一個「rush update」​

在複製專案檔案之後，我們需要編輯 rush.json，並在 projects 清單下新增類似這樣的項目

  "projects": [
    {
      "packageName": "my-toolchain",
      "projectFolder": "tools/my-toolchain"
    }
  ]

這會告訴 Rush 它應該管理此專案。

為何 Rush 無法自動偵測我的專案？

Rush 不會使用萬用字元自動探索專案。我們做出此設計決策有一些動機

  1. 深度優先掃描成本很高，尤其是在工具需要重複收集清單時。
  2. 在快取 CI 電腦上，掃描可能會意外地挑選出上一個建置中遺留的檔案。
  3. 擁有所有專案及其重要中繼資料的集中清單會很有用。例如，這會讓核准/原則功能更加直覺。

接下來，執行 rush update 以安裝 my-toolchain 的相依性。此指令可以在包含 rush.json 的儲存庫資料夾的任何子資料夾中執行

~/my-repo$ rush update
~/my-repo$ git add .
~/my-repo$ git commit -m "rush update"

由於這是儲存庫的第一個專案，您會注意到 rush update 會建立數個新的檔案

  • common/config/rush/shrinkwrap.yaml：通用縮排檔 (這裡假設我們使用的是 PNPM 套件管理員)
  • common/scripts/install-run-rush.js：由 CI 作業用來以可靠的方式啟動 Rush 工具
  • common/scripts/install-run.js：由 CI 作業用來以可靠的方式啟動任意工具

步驟 6：確認新專案是否建置​

為了建置您的專案，Rush 會在您的 package.json 檔案的 "scripts" 區段中尋找 "build" 指令碼。在 rush-example 的範例中，專案會使用簡單的 Shell 指令碼 "rimraf ./lib/ && tsc" 進行建置

{
  "name": "my-toolchain",
  "version": "1.0.0",
  "description": "An example toolchain used to build projects in this repo",
  "license": "MIT",
  "bin": {
    "my-build": "bin/my-build.js"
  },
  "scripts": {
    "build": "rimraf ./lib/ && tsc"
  },
  "dependencies": {
    "colors": "^1.3.2"
  },
  "devDependencies": {
    "@types/node": "^10.9.4",
    "rimraf": "^2.6.2",
    "typescript": "^3.0.3"
  }
}

建立 "build" 指令碼時，請記住以下幾點

  • Rush 通常會使用您的系統 PATH 環境變數來尋找指令碼命令。不過，如果您指定單字命令 (例如 "heft" 或 "make")，Rush 會先在 common\temp\node_modules\.bin 資料夾中尋找程式。

  • 如果處理程序傳回非零的結束狀態，Rush 會假設發生失敗，並會封鎖下游建置。

  • 如果命令將任何內容寫入 stderr 資料流，Rush 會將此解讀為至少報告一個錯誤或警告。這會中斷建置。(這是依設計的 -- 如果您允許人們合併「狼來了」的 PR，您很快就會發現累積了太多警告，以致於沒有人再閱讀它們。) 某些工具程式庫 (例如 Jest) 會在正常作業期間寫入 stderr；您需要重新導向它們的輸出。

  • 如果某些專案不需要由 rush build 處理，您仍然需要 build 項目。將值設定為空字串 ("")，Rush 就會忽略它。

現在，我們試著建置您的專案。從包含 rush.json 的資料夾下的任何位置執行此指令 (這會建置儲存庫中的所有專案)

rush build

Rush 提供許多用於建置專案的命令列切換器。如需詳細資訊，請參閱 rush build 和 rush rebuild。

虛擬相依性錯誤

Rush 和 PNPM 使用符號連結來防止專案導入幽靈依賴。如果您的 package.json 檔案中未宣告 NPM 依賴項，則當您的專案嘗試導入它時可能會發生執行階段錯誤。這些幽靈依賴錯誤是在將現有專案遷移到 Rush monorepo 時最常見的問題之一。通常，解決方法很簡單，只需將缺少的依賴項添加到您的 package.json 檔案中即可。

rush scan 命令是一種快速偵測這些問題的方法。

步驟 7：新增更多專案​

您可以按照步驟 4 中的相同操作來新增更多專案。在我們的範例中，我們會先新增 my-controls（因為它依賴於 my-toolchain），然後最後新增 my-application（因為它依賴於所有其他專案）。我們主動新增了一些類別資料夾（「libraries」和「apps」），因為我們預期在我們的場景中會有更多這種類型的東西。填寫後的 "projects" 區段如下所示

  "projects": [
    {
      "packageName": "my-app",
      "projectFolder": "apps/my-app"
    },

    {
      "packageName": "my-controls",
      "projectFolder": "libraries/my-controls",
      "reviewCategory": "production"
    },

    {
      "packageName": "my-toolchain",
      "projectFolder": "tools/my-toolchain",
      "reviewCategory": "tools"
    }
  ]

一旦您新增了所有專案並在沒有錯誤的情況下建置完成，您可以考慮啟用其他可選功能。設定檔中包含許多您可以取消註解以開始使用的程式碼片段。rush-example 儲存庫使用其中一些程式碼片段。