IDX 提供了各种内置模板,其中包括用户可能需要快速开始使用某种语言或框架的所有文件、系统软件包(例如编译器)和扩展程序。
您可能还需要创建用户可配置的专属模板。例如:
如果您要构建自己的框架、库或服务,则可以利用云端虚拟机的全部功能,让用户无需离开浏览器就能快速上手您的技术。
如果您有项目的首选技术栈,则可以使用自定义模板简化自己的新项目启动流程。
如果您正在教其他人(例如通过 Codelab),可以通过将 Codelab 的起点预配置为自定义模板来为学生移除一些初始步骤。
准备好自定义模板后,您可以创建一个链接,将其放置在您的网站、Git 代码库 README
文件、软件包详情页面(例如 NPM 中)或用户可能希望开始使用您的技术的其他地方。
前提条件
在开始之前,请确保您已熟悉如何使用 .idx/dev.nix
文件自定义环境。
模板还使用 Nix 语言,因此您可能需要复习一些基础知识,或将其用作便捷参考。
模板文件结构
模板是包含至少两个文件的公共 GitHub 代码库(或代码库中的文件夹或分支):
-
idx-template.json
包含模板的元数据,包括其用户可见名称、说明以及可供用户配置模板的参数。例如,您可以允许用户从多种编程语言中进行选择,或者提供示例用例。当用户选择通过模板创建新工作区时,IDX 会使用这些信息来准备向用户显示的界面。 idx-template.nix
是使用 Nix 语言编写的文件,其中包含一个 Bash shell 脚本(封装在 Nix 函数中),负责执行以下操作:- 创建新工作区的工作目录并
- 通过创建
.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
来向引导脚本脚本提供其他系统软件包,就像通过在 dev.nix
文件中向 packages
添加 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 使用此文件中的信息来准备向模板用户显示的界面(例如复选框、下拉列表和文本字段)。 - 更新
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),因此界面将呈现这两个选项的单选按钮组,并将值 ts
或 js
传递给 idx-template.nix
脚本。
每个参数对象都具有以下属性:
媒体资源 | TYPE | 说明 |
---|---|---|
id | string |
参数的唯一 ID,类似于变量名称。 |
name | string |
此参数的显示名。 |
类型 | string |
指定要用于此参数的界面组件,以及要传递给引导加载程序脚本的数据类型。有效值包括:
|
选项 | object |
对于 enum 参数,这表示要向用户显示的选项。例如,如果选项为 {"js": "JavaScript", ...} ,则“JavaScript”将显示为选项,选中后,此参数的值将为 js 。 |
default | string 或boolean |
设置界面中的初始值。对于 enum 参数,这必须是 options 中的键之一。对于 boolean 参数,这应该是 true 或 false 。 |
必填 | boolean |
指示此参数是必需的。 |
使用 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 = { ... };
};
}
基于模板创建新工作区
对模板进行端到端测试的最简单方法是使用该模板创建新的工作区。访问以下链接,将示例替换为您模板的 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 中打开”按钮。