內部套件

內部套件是原始碼位於您的工作區內的函式庫。您可以快速建立內部套件，以便在您的單一儲存庫中共享程式碼，並選擇在稍後需要時將它們發佈到 npm 註冊表。

內部套件透過將它們安裝在 package.json 中來在您的儲存庫中使用，這類似於來自 npm 註冊表的外部套件。但是，您可以使用套件管理員的工作區安裝語法來引用套件，而不是標記要安裝的版本

{
  "dependencies": {
    "@repo/ui": "*"
  }
}

在建立內部套件指南中，您可以從頭開始使用編譯套件策略來建置內部套件。在本頁面中，我們將描述建立內部套件的其他策略及其權衡，包括將套件發佈到 npm 註冊表以建立外部套件。

然後，您可以像使用外部套件一樣，將套件匯入到您的程式碼中

import { Button } from '@repo/ui'; 
 
export default function Page() {
  return <Button>Submit</Button>;
}

編譯策略

根據您對函式庫的需求，您可以選擇三種編譯策略之一

• 即時套件：透過允許應用程式捆綁器在使用套件時編譯套件，為您的套件建立最少的設定。
• 編譯套件：使用適度的設定，使用建置工具（如 tsc 或捆綁器）編譯您的套件。
• 可發佈套件：編譯並準備套件以發佈到 npm 註冊表。此方法需要最多的設定。

即時套件

即時套件由使用它的應用程式編譯。這表示您可以直接使用 TypeScript（或未編譯的 JavaScript）檔案，與此頁面上的其他策略相比，需要的設定少得多。

此策略在以下情況下最有用

• 您的應用程式是使用現代捆綁器（如 Turbopack、webpack 或 Vite）建置的。
• 您想要避免設定和設定步驟。
• 即使您無法命中套件的快取，您也對應用程式的建置時間感到滿意。

即時套件的 package.json 可能看起來像這樣

{
  "name": "@repo/ui",
  "exports": {
    "./button": "./src/button.tsx",
    "./card": "./src/card.tsx"
  },
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "check-types": "tsc --noEmit"
  }
}

在此 package.json 中，有幾件重要的事情需要注意

• 直接匯出 TypeScript：exports 欄位標記套件的進入點，在本例中，您是直接引用 TypeScript 檔案。這是可能的，因為應用程式的捆綁器將在建置過程中編譯程式碼。
• 沒有 build 指令碼：由於此套件正在匯出 TypeScript，因此它不需要建置步驟來轉譯套件。這表示您不必在此套件中設定建置工具，即可使其在您的工作區中運作。

限制和權衡

• 僅適用於消費者進行轉譯時：此策略只能在套件將用於使用捆綁器或原生理解 TypeScript 的工具時使用。消費者的捆綁器負責將 TypeScript 套件轉譯為 JavaScript。如果您的建置或其他套件用法無法使用 TypeScript，您將需要轉移到編譯套件策略。
• 沒有 TypeScript paths：正在由其消費者轉譯的函式庫無法使用 compilerOptions.paths 設定，因為 TypeScript 假設原始碼正在撰寫套件中進行轉譯。如果您使用的是 TypeScript 5.4 或更高版本，我們建議使用 Node.js 子路徑匯入。若要了解如何操作，請造訪我們的 TypeScript 頁面。
• Turborepo 無法快取即時套件的建置：由於套件沒有自己的 build 步驟，因此 Turborepo 無法快取它。如果您想要將設定保持在最低限度，並且可以接受應用程式的建置時間，則此權衡對您來說可能是有意義的。
• 將報告內部依賴項中的錯誤：當直接匯出 TypeScript 時，如果內部依賴項中的程式碼有 TypeScript 錯誤，則依賴套件中的類型檢查將會失敗。在某些情況下，您可能會發現這令人困惑或有問題。

編譯套件

編譯套件是使用建置工具（如 tsc (TypeScript 編譯器)）處理自身編譯的套件。

{
  "name": "@repo/ui",
  "exports": {
    "./button": {
      "types": "./src/button.tsx",
      "default": "./dist/button.js"
    },
    "./card": {
      "types": "./src/card.tsx",
      "default": "./dist/card.js"
    }
  },
  "scripts": {
    "build": "tsc"
  }
}

編譯您的函式庫會將編譯後的 JavaScript 輸出產生到目錄（dist、build 等），您將使用這些目錄作為套件的進入點。一旦建置輸出新增到任務的 outputs 金鑰，Turborepo 將快取這些輸出，讓您擁有更快的建置時間。

限制和權衡

• 使用 TypeScript 編譯器：大多數編譯套件應使用 tsc。由於套件很可能被使用捆綁器的應用程式使用，因此應用程式的捆綁器將準備函式庫套件以在應用程式的最終捆綁中發佈，處理 polyfill、降級和其他問題。只有在您有需要它的特定用例時才應使用捆綁器，例如將靜態資源捆綁到套件的輸出中。
• 更多設定：編譯套件需要更深入的知識和設定才能建立建置輸出。TypeScript 編譯器有許多設定，可能難以管理和理解，以及用於優化捆綁器的進一步設定，例如 package.json 中的 sideEffects 金鑰。您可以在我們專門的 TypeScript 指南中找到我們的一些建議。

可發佈套件

將套件發佈到 npm 註冊表對此頁面上的封裝策略提出了最嚴格的要求。因為您不了解從註冊表下載套件的消費者將如何使用您的套件，所以由於穩健套件所需的眾多設定，您可能會發現它很困難。

此外，將套件發佈到 npm 註冊表的過程需要專業知識和工具。我們建議使用 changesets 來管理版本控制、變更日誌和發佈過程。

如需詳細指南，請造訪我們的發佈套件指南。