创建自定义模板

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Firebase Studio 提供了各种内置模板，包含快速上手某种语言或框架所需的所有文件、系统软件包（例如编译器）和扩展程序。

您还可以使用 GitHub 上托管的社区模板启动 Firebase Studio 工作区。如需详细了解如何从模板启动新工作区，请参阅创建 Firebase Studio 工作区。

大多数用户会使用内置模板或从 Git 导入项目，但对于更高级的用例，您可以创建自己的模板：

• 如果您构建自己的框架、库或服务，可以让用户直接在浏览器中利用基于云的虚拟机快速上手您的技术。

• 如果您偏好使用某个技术栈来开发项目，则可以使用自定义模板简化启动新项目的流程。

• 如果您正在进行教学（例如通过教程或 Codelab），可以通过将 Codelab 的起始点预先配置为自定义模板，帮助学员跳过初始步骤。

创建并测试自定义模板后，您可以为其创建链接，并将该链接放置在您的网站、Git 代码库 README 文件、软件包详情页面（例如，在 NPM 中）或您希望用户开始使用您的技术的任何其他位置。

前提条件

准备工作：

• 了解如何使用 idx/dev.nix 文件自定义您的环境。

• 熟悉 Nix 语言的基础知识，并方便随时查阅参考资料。

模板文件结构

Firebase Studio 模板是一个公共 Git 代码库（或其中的文件夹或分支），其中至少包含两个文件：

• idx-template.json 包含模板的元数据，包括对用户可见的名称、说明以及用户可用于配置模板的参数。例如，您可以允许用户选择多种编程语言或示例用例。Firebase Studio 会使用这些信息生成用户从模板创建新工作区时看到的界面。

• idx-template.nix 是使用 Nix 语言编写的文件，包含一个由 Nix 函数封装的 Bash shell 脚本，用于：

  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 使用此文件中的信息来准备向模板用户显示的界面（例如复选框、下拉菜单和文本字段）。
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），界面将为这两个选项呈现一个单选按钮组，并将值 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 = { ... };
  };
}

选择默认的工作区图标

您可以通过将名为 icon.png 的 PNG 文件放在 .idx 目录中的 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 代码库，并分享您创建用于测试的工作区时使用的链接。

为了让用户更轻松地找到您的模板，请在您的网站或代码库的自述文件中添加“在 Firebase Studio 中打开”按钮。