建立自訂範本

Firebase Studio 提供多種內建範本，其中包含所有檔案、系統套件 (例如編譯器) 和擴充功能，可讓您快速開始使用語言或架構。

您也可以使用 GitHub 代管的社群範本啟動 Firebase Studio 工作區。如要進一步瞭解如何從範本啟動新工作區，請參閱「建立 Firebase Studio 工作區」。

大多數使用者會使用內建範本，或從 Git 匯入專案，但針對更進階的用途，您可以自行建立範本：

• 如果您自行建構架構、程式庫或服務，可以讓使用者在瀏覽器中快速開始使用您的技術，充分發揮雲端虛擬機器的強大功能。

• 如果您有專案偏好的技術堆疊，可以使用自訂範本簡化啟動新專案的程序。

• 如果您要教導他人，例如透過教學課程或程式碼研究室，可以預先將程式碼研究室的起始點設為自訂範本，藉此移除學生的部分初始步驟。

建立及測試自訂範本後，您可以建立連結，放置在網站、Git 存放區 README 檔案、套件詳細資料頁面 (例如 NPM 中)，或任何您希望使用者開始使用技術的其他位置。

事前準備

事前準備作業：

• 瞭解如何使用 idx/dev.nix 檔案自訂環境。

• 熟悉 Nix 語言的基本概念，並隨時參考相關資料。

範本檔案結構

Firebase Studio 範本是至少包含兩個檔案的公開 Git 存放區 (或存放區中的資料夾或分支)：

• idx-template.json 包含範本的中繼資料，包括使用者可見的名稱、說明，以及可供使用者設定範本的參數。舉例來說，您可以讓使用者從多種程式設計語言或示例用途中進行選擇。Firebase Studio 會使用這項資訊，為使用者準備 UI，讓他們選擇從範本建立新工作區。

• idx-template.nix 是使用 Nix 語言編寫的檔案，其中包含 Bash 殼層指令碼 (包裝在 Nix 函式中)，可執行以下操作：

  1. 建立新工作區的工作目錄。

  2. 透過建立 .idx/dev.nix 檔案來設定環境。請注意，您也可以在這個指令碼中執行專案架構工具，例如 flutter create 或 npm init，或是執行以 Go、Python、Node.js 或其他語言編寫的自訂指令碼。

     當 Firebase Studio 載入範本時，這個檔案會使用使用者指定的參數執行。

您可以將其他檔案與這兩個檔案一併納入，以便在 idx-template.nix 中使用，以便將範本例項化。舉例來說，您可以加入最終 .idx/dev.nix 檔案，甚至直接在存放區中加入所有結構檔案。

建立起始範本

為加快範本建立作業，建議您先使用下列其中一種方法建立 Firebase Studio 範本，再進一步自訂：

• 將任何公開的 GitHub 存放區轉換為範本
• 使用官方或社群範本做為範本的基礎

基本範例：將任何公開 GitHub 存放區轉換為範本

在進一步瞭解如何定義 idx-template.json 和 idx-template.nix 之前，建議您先查看以下基本範例範本：

• 不含使用者可設定的參數。
• 將範本存放區中的所有檔案 (兩個 idx-template 檔案除外) 複製到使用者的工作區。應該已經有一個 .idx 子資料夾，其中包含定義環境的 dev.nix 檔案。

如果您將下列檔案新增至任何公開的 GitHub 存放區 (或子資料夾或分支)，就會有效地將該存放區轉換為 Firebase Studio 範本。

idx-template.json

{
  "name": "Hello world",
  "description": "A template for a CLI program that prints 'hello world'",
  "icon": "https://www.gstatic.com/images/branding/productlogos/studio/v1/192px.svg",
  "params": []
}

idx-template.nix

# No user-configurable parameters
{ pkgs, ... }: {
  # Shell script that produces the final environment
  bootstrap = ''
    # Copy the folder containing the `idx-template` files to the final
    # project folder for the new workspace. ${./.} inserts the directory
    # of the checked-out Git folder containing this template.
    cp -rf ${./.} "$out"

    # Set some permissions
    chmod -R +w "$out"

    # Remove the template files themselves and any connection to the template's
    # Git repository
    rm -rf "$out/.git" "$out/idx-template".{nix,json}
  '';
}

請參閱「自訂範本」一文，瞭解您可以進行哪些額外變更來自訂範本。

使用官方或社群範本建立自訂範本

Firebase Studio 團隊維護兩個 Firebase Studio 範本存放區：

• 官方範本：這是指您在建立新應用程式時，直接從 Firebase Studio 資訊主頁選取的範本。

• 社群範本：這些範本允許開放原始碼社群提供貢獻。如要使用社群範本，請複製社群範本 Git 存放區。您可以使用要使用的範本完整連結。

如要以現有範本為基礎建立自訂範本，請按照下列步驟操作：

1. 決定要使用哪個範本做為自訂範本的基礎，然後複製專案。

2. 視需要自訂 idx-template.json、idx-template.nix 和 .idx/dev.nix，請參閱「自訂範本」一文。

3. 檢查存放區中的變更。

4. 請按照「為範本建立新工作區」中的步驟，發布及測試範本。如果您使用的是巢狀存放區，請在網址中直接連結至該存放區。舉例來說，如果您使用社群「Vanilla Vite」範本，則會使用以下網址佈建及測試新工作區：

   https://studio.firebase.google.com/new?template=https://github.com/project-idx/community-templates/tree/main/vite-vanilla
   

請參閱「自訂範本」一文，瞭解您可以進行哪些額外變更來自訂範本。

自訂範本

您已建立可用於建構的基礎範本，現在可以編輯 idx-template.json、idx-template.nix 和 .idx/dev.nix 檔案，以符合您的需求。您可能需要自訂其他設定：

• 將系統套件新增至 bootstrap 指令碼。
• 新增可由使用者設定的參數
• 選擇預設要開啟的檔案
• 選擇預設工作區圖示

在 bootstrap 指令碼中使用其他系統套件

基本範例只會使用基本 POSIX 指令，將檔案複製到正確的位置。範本的 bootstrap 指令碼可能需要安裝其他二進位檔，例如 git、node、python3 或其他檔案。

您可以在 idx-template.nix 檔案中指定 packages，讓系統套件可供引導程式指令碼使用，就像使用其他系統套件自訂工作區一樣，在 dev.nix 檔案中新增 packages。

以下是新增 pkgs.nodejs 的範例，其中包含 node、npx 和 npm 等二進位檔：

# idx-template.nix
{pkgs}: {
  packages = [
    # Enable "node", "npm" and "npx" in the bootstrap script below.
    # Note, this is NOT the list of packages available to the workspace once
    # it's created. Those go in .idx/dev.nix
    pkgs.nodejs
  ];

  bootstrap = ''
    mkdir "$out"
    # We can now use "npm"
    npm init --yes my-boot-strap@latest "$out"
  ''
}

新增可由使用者設定的參數

如要讓使用者自訂新專案的起點，您可以建立多個範本，或建立含有參數的單一範本。如果不同的起點只是傳遞至 CLI 工具的不同值 (例如 --language=js 與 --language=ts)，這會是個不錯的選項。

如要新增參數，請按照下列步驟操作：

1. 在 idx-template.json 中繼資料檔案的 params 物件中說明參數。Firebase Studio 會使用這個檔案中的資訊，為範本使用者準備要顯示的 UI (例如核取方塊、下拉式選單和文字欄位)。
2. 更新 idx-template.nix 引導程序，以便使用使用者在例項化範本時選取的值。

在 idx-template.json 中說明您的參數

以下是新增 enum 參數的範例，Firebase Studio 會視選項數量顯示為下拉式選單或圓形按鈕群組：

{
  "name": "Hello world",
  "description": "A hello world app",
  "params": [
    {
      "id": "language",
      "name": "Programming Language",
      "type": "enum",
      "default": "ts",
      "options": {
        "js": "JavaScript",
        "ts": "TypeScript"
      },
      "required": true
    }
  ]
}

由於有兩個值 (JavaScript 和 TypeScript)，UI 會為這兩個選項顯示單選按鈕群組，並將 ts 或 js 值傳遞至 idx-template.nix 指令碼。

每個參數物件都具有下列屬性：

在 idx-template.nix 中使用參數值

在 idx-template.json 檔案中定義 params 物件後，您就可以開始根據使用者選擇的參數值自訂引導程式指令碼。

按照上一節的範例，如果您有一個 ID 為 language 的單一參數，該參數為列舉，可能的值為 ts 或 js，您可以這樣使用：

# idx-template.nix
# Accept additional arguments to this template corresponding to template
# parameter IDs, including default values (language=ts by default in this example).
{ pkgs, language ? "ts", ... }: {
  packages = [
    pkgs.nodejs
  ];

  bootstrap = ''
    # We use Nix string interpolation to pass the user's chosen programming
    # language to our script.
    npm init --yes my-boot-strap@latest "$out" -- --lang=${language}
  ''
}

另一個常見的模式是根據字串值條件式加入內容。您也可以透過以下方式編寫上述範例：

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

選擇預設要開啟的檔案

建議您在使用範本建立新工作區時，自訂要開啟哪些檔案進行編輯。舉例來說，如果您的範本是用於基本網站，建議您開啟主要 HTML、JavaScript 和 CSS 檔案。

如要自訂預設開啟的檔案，請更新 .idx/dev.nix 檔案 (不是 idx-template.nix 檔案！)，加入具有 openFiles 屬性的 onCreate 工作區掛鉤，如下所示：

# .idx/dev.nix
{pkgs}: {
  ...
  idx = {
    # Workspace lifecycle hooks
    workspace = {
      # Runs when a workspace is first created with this `dev.nix` file
      onCreate = {
        # Open editors for the following files by default, if they exist.
        # The last file in the list will be focused.
        default.openFiles = [
          "src/index.css"
          "src/index.js"
          "src/index.html"
        ];
        # Include other scripts here, as needed, for example:
        # installDependencies = "npm install";
      };
      # To run something each time the workspace is (re)started, use the `onStart` hook
    };
    # Enable previews and customize configuration
    previews = { ... };
  };
}

選擇預設工作區圖示

您可以選擇使用範本建立的工作區預設圖示，方法是在 .idx 目錄中，將名為 icon.png 的 PNG 檔案放在 dev.nix 檔案旁邊。

在新的工作區中測試範本

如要測試範本的端對端功能，最簡單的方法就是使用範本建立新的工作區。請造訪下列連結，並將範例替換為範本的 GitHub 存放區網址：

https://idx.google.com/new?template=https://github.com/my-org/my-repo

您可以選擇加入分支和子資料夾。只要可公開存取，下列所有項目皆有效：

• https://github.com/my-org/my-repo/
• https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplate
• https://github.com/my-org/my-repo/tree/branch
• https://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate

這個網址也是您要與他人分享的網址，讓他們可以使用新的範本，或是您要從「在 Firebase Studio 中開啟」按鈕連結到的網址。

共用範本

確認範本的運作情形符合預期後，請將範本發布至 GitHub 存放區，並分享您在建立用於測試的工作區時使用的連結。

如要讓使用者更容易找到範本，請在網站或存放區的 README 中加入「Open in Firebase Studio」按鈕。