IDX にはさまざまな組み込みテンプレートが用意されており、言語やフレームワークをすぐに使用するために必要なすべてのファイル、システム パッケージ(コンパイラなど)、拡張機能が含まれています。
ユーザーが構成可能な独自のテンプレートを作成することもできます。次に例を示します。
独自のフレームワーク、ライブラリ、またはサービスを構築している場合、ユーザーはクラウドベースの仮想マシンの機能を最大限に活用して、ブラウザから離れることなく、自社のテクノロジーをすぐに利用できます。
プロジェクトに適した技術スタックがある場合は、カスタム テンプレートを使用して新しいプロジェクトを開始するプロセスを簡素化できます。
Codelab を通じて他の人に教える場合は、Codelab の開始点をカスタム テンプレートとして事前に構成することで、受講生の最初の手順の一部を削除できます。
カスタム テンプレートの準備ができたら、そのリンクを作成して、ウェブサイト、Git リポジトリ README
ファイル、パッケージの詳細ページ(NPM など)、ユーザーがテクノロジーの利用を開始する可能性がある場所に配置できます。
前提条件
始める前に、.idx/dev.nix
ファイルを使用した環境のカスタマイズについて理解しておいてください。
テンプレートでは Nix 言語も使用されているため、基本を復習したり、参照用に手元に置いたりできます。
テンプレート ファイル構造
テンプレートは、少なくとも 2 つのファイルを含む公開 GitHub リポジトリ(またはリポジトリ内のフォルダまたはブランチ)です。
カスタム テンプレートから新しいワークスペースを作成する idx-template.json
には、ユーザーに表示される名前、説明、ユーザーがテンプレートを構成するために利用できるパラメータなど、テンプレートのメタデータが含まれます。たとえば、さまざまなプログラミング言語やサンプル ユースケースからユーザーが選択できるようにすることができます。IDX はこの情報を使用して、ユーザーがテンプレートから新しいワークスペースを作成するときに表示される UI を準備します。idx-template.nix
は Nix 言語で記述されたファイルであり、以下の処理を行う Bash シェル スクリプト(Nix 関数でラップ)が含まれています。- 新しいワークスペースの作業ディレクトリを作成し、
.idx/dev.nix
ファイルを作成して環境を設定します。このスクリプトでは、flutter create
やnpm init
などのプロジェクト スキャフォールディング ツールのみを実行することも、Go、Python、Node.js などの言語で記述されたカスタム スクリプトを実行することもできます。
このファイルは、テンプレートの構成時にユーザーが指定したパラメータで実行されます。
テンプレートをインスタンス化するために、他のファイルをこの 2 つのファイルとともに idx-template.nix
で使用できます。たとえば、最終的な .idx/dev.nix
ファイルを含めることも、すべてのスキャフォールディング ファイルをリポジトリに直接含めることもできます。
基本的な例: 公開されている GitHub リポジトリをテンプレートに変換する
idx-template.json
と idx-template.nix
の定義方法の詳細に入る前に、次のような基本的なサンプル テンプレートを確認しておくと役に立ちます。
- ユーザーが構成可能なパラメータがない
- テンプレート リポジトリ内のすべてのファイル(2 つの
idx-template
ファイルを除く)をユーザーのワークスペースにコピーするだけで済みます。環境を定義するdev.nix
ファイルを含む.idx
サブフォルダがすでに存在します。
次のファイルを 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
を指定することで、追加のシステム パッケージをブートストラップ スクリプトで使用できるようにできます。これは、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
など)に最適なオプションです。
パラメータを追加する手順は次のとおりです。
idx-template.json
メタデータ ファイルのparams
オブジェクトにパラメータを記述します。IDX はこのファイルの情報を使用して、テンプレートのユーザーに表示される UI(チェックボックス、プルダウン、テキスト フィールドなど)を作成します。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
}
]
}
2 つの値(JavaScript と TypeScript)があるため、UI は 2 つのオプションのラジオボタン グループをレンダリングし、値 ts
または js
のいずれかを idx-template.nix
スクリプトに渡します。
各パラメータ オブジェクトには次のプロパティがあります。
プロパティ | タイプ | 説明 |
---|---|---|
id | string |
パラメータの一意の ID(変数名と同様)。 |
name | string |
このパラメータの表示名。 |
type | string |
このパラメータに使用する UI コンポーネントと、ブートストラップ スクリプトに渡すデータ型を指定します。指定できる値は次のとおりです。
|
オプション | object |
enum パラメータの場合、ユーザーに表示するオプションを表します。たとえば、オプションが {"js": "JavaScript", ...} の場合、オプションとして「JavaScript」が表示され、選択すると、このパラメータの値は js になります。 |
default | string または boolean |
UI の初期値を設定します。enum パラメータの場合、これは options のキーのいずれかにする必要があります。boolean パラメータの場合、true または false にする必要があります。 |
不要です | boolean |
このパラメータが必須であることを示します。 |
idx-template.nix
でパラメータ値を使用する
idx-template.json
ファイルで params
オブジェクトを定義したら、ユーザーが選択したパラメータ値に基づいてブートストラップ スクリプトのカスタマイズを開始できます。
前のセクションの例に従って、取り得る値が ts
または js
の列挙型である ID language
を持つ単一のパラメータがある場合は、次のように使用できます。
# 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}
''
}
もう 1 つの一般的なパターンは、文字列の値に応じて、条件付きでコンテンツを含める方法です。上の例は、次のように記述することもできます。
npm init --yes my-boot-strap@latest "$out" -- \
${if language == "ts" then "--lang=ts" else "--lang=js" }
デフォルトで開くファイルを選択する
テンプレートを使用して新しいワークスペースを作成するときに、どのファイルを開いて編集するかをカスタマイズすることをおすすめします。たとえば、テンプレートが基本的なウェブサイト用のものである場合は、メインの HTML、JavaScript、CSS ファイルを開いておくことをおすすめします。
デフォルトで開くファイルをカスタマイズするには、(idx-template.nix
ファイルではなく).idx/dev.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 リポジトリ URL に置き換えます。
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
この URL は、他のユーザーが新しいテンプレートを使用できるようにするために他のユーザーと共有する URL、または [IDX で開く] ボタンからリンクする URL です。
テンプレートを共有する
テンプレートが想定どおりに動作していることを確認したら、GitHub リポジトリに公開し、テスト用ワークスペースの作成時に使用したものと同じリンクを共有します。
また、ユーザーがテンプレートを見つけやすくするために、ウェブサイトまたはリポジトリの README に「IDX で開く」ボタンを追加します。