建立自訂範本

IDX 提供多種內建的範本，其中包含所有檔案、系統套件 (例如編譯器) 以及擴充功能，使用者可能需要快速開始使用某個語言或架構。

您也可以自行建立可供使用者設定的範本。例如：

  • 如果您正在建構自己的架構、程式庫或服務，可以讓使用者在不離開瀏覽器的情況下，快速開始使用您的技術，而無須離開瀏覽器，就能享有完整的雲端虛擬機器。

  • 如果您有專案偏好的技術堆疊，就能簡化透過自訂範本開始新專案的流程。

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

自訂範本準備就緒後，您可以為其建立連結，並放到您的網站、Git 存放區 README 檔案、套件詳細資料頁面 (例如 NPM)，或使用者可能想開始使用技術的其他位置。

先備知識

在開始之前，請確認您已瞭解如何使用 .idx/dev.nix 檔案自訂環境。

範本也使用 Nix 語言，因此建議您溫習一些基礎知識，或將其留做參考。

範本檔案結構

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

  • 對話方塊使用者透過您的範本建立新工作區時會看到的對話方塊
    透過自訂範本建立新的工作區

    idx-template.json 包含範本的中繼資料，包括其向使用者顯示的名稱、說明，以及可供使用者用來設定範本的參數。例如，您可以讓使用者從多種程式設計語言或用途範例中進行選擇。IDX 會根據這項資訊，在使用者選擇從您的範本建立新工作區時，準備向使用者顯示的 UI。

  • idx-template.nix 是使用 Nix 語言編寫的檔案，內含一個 Bash 殼層指令碼 (包裝在 Nix 函式中)，其負責：

    1. 建立新工作區的工作目錄
    2. 建立 .idx/dev.nix 檔案來設定環境。請注意，您也可以用這段指令碼執行專案鷹架工具 (例如 flutter create 或 npm init)，或是執行以 Go、Python、Node.js 或其他語言編寫的自訂指令碼。

    此檔案會在設定範本時以使用者指定的參數執行。

其他檔案可與這兩個檔案一起納入，以便用於 idx-template.nix 中，以便對範本執行個體化。舉例來說，您可以納入最終的 .idx/dev.nix 檔案，或甚至直接在存放區中加入所有鷹架檔案。

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

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

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

將下列檔案新增至任何公開 GitHub 存放區 (或子資料夾或分支版本)，實際上會將該存放區轉換成 IDX 範本。

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/idx/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}
  '';
}

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

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

您可以在 idx-template.nix 檔案中指定 packages，向 Bootstrap 指令碼提供其他系統套件，方法與透過其他系統套件自訂工作區一樣，只要在其 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 物件中說明參數。IDX 會使用這個檔案中的資訊，準備範本使用者看到的 UI (例如核取方塊、下拉式選單和文字欄位)。
  2. 更新 idx-template.nix 啟動程序，以在範本例項化時使用使用者選取的值。

說明 idx-template.json 中的參數

以下範例說明如何新增 enum 參數，視選項數量而定，IDX 會顯示為下拉式選單或圓形按鈕群組。

{
  "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 指令碼。

每個參數物件都包含下列屬性：

屬性 TYPE 說明
ID string 參數的專屬 ID，與變數名稱類似。
名稱 string 這個參數的顯示名稱。
類型 string

指定要用於這個參數的 UI 元件，以及要傳遞至 Bootstrap 指令碼的資料類型。以下為有效值：

  • "enum" - 顯示下拉式選單或圓形按鈕群組，並將 string 傳遞至 Bootstrap
  • "boolean" - 顯示核取方塊和票證 true 或 false
  • "text" - 顯示文字欄位並傳遞 string
選項 object 如果是 enum 參數，代表向使用者顯示的選項。舉例來說，如果選項是 {"js": "JavaScript", ...}，就會顯示「JavaScript」選項；如果選取此參數值，則該參數值為 js。
預設 string 或 boolean 在 UI 中設定初始值。針對 enum 參數，這必須是 options 中的其中一個鍵。如果是 boolean 參數，這應為 true 或 false。
必填 boolean 表示必要參數。

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

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

按照上一節的範例，如果您有 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 = { ... };
  };
}

使用範本建立新的工作區

如要端對端測試範本，最簡單的方法就是使用該範本建立新的工作區。請造訪下列連結，並將範例替換為範本的 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

這也會是您與他人分享的網址，以便對方使用您的新範本或您「在 IDX 中開啟」按鈕的連結。

共用範本

確認範本可正常運作後，請將範本發布至 GitHub 存放區，並分享在建立測試用工作區時使用的連結。

此外，如要讓使用者更容易找到您的範本，請在網站或存放區 README 中新增「在 IDX 中開啟」按鈕。