Как создать пользовательский шаблон

Firebase Studio предлагает широкий спектр встроенных шаблонов , включающих все необходимые файлы, системные пакеты (например, компиляторы) и расширения, позволяющие быстро начать работу с выбранным языком программирования или фреймворком.

Вы также можете запустить рабочую область Firebase Studio используя шаблоны сообщества , размещенные на GitHub. Дополнительную информацию о запуске новой рабочей области из шаблона см. в разделе «Создание рабочей области Firebase Studio .

Большинство пользователей будут использовать встроенные шаблоны или импортировать проекты из Git, но для более сложных случаев вы можете создавать собственные шаблоны:

• Если вы разрабатываете собственный фреймворк, библиотеку или сервис , вы можете позволить пользователям быстро начать работу с вашей технологией, не покидая браузер, используя всю мощь облачной виртуальной машины.

• Если у вас есть предпочтительный технологический стек для ваших проектов , вы можете упростить процесс запуска новых проектов с помощью пользовательского шаблона.

• Если вы обучаете других, например, с помощью учебного пособия или практического занятия , вы можете упростить некоторые начальные шаги для своих студентов, предварительно настроив отправную точку для вашего практического занятия в качестве пользовательского шаблона.

После создания и тестирования пользовательского шаблона вы можете создать ссылку на него, которую можно разместить на вашем веб-сайте, в файле README репозитория Git, на странице с подробным описанием пакета (например, в NPM) или в любом другом месте, где, как вы ожидаете, пользователи начнут использовать вашу технологию.

Предварительные требования

Прежде чем начать:

• Узнайте, как использовать файл idx/dev.nix для настройки вашей среды .

• Ознакомьтесь с основами языка Nix и держите справочник под рукой.

Структура шаблонных файлов

Шаблон Firebase Studio — это общедоступный репозиторий Git (или папка, или ветка в репозитории), содержащий как минимум два файла:

• idx-template.json содержит метаданные для шаблона, включая его видимое пользователю имя, описание и параметры, доступные пользователям для настройки шаблона. Например, вы можете разрешить пользователям выбирать из нескольких языков программирования или примеров использования. Firebase Studio использует эту информацию для подготовки пользовательского интерфейса, отображаемого пользователям при создании нового рабочего пространства на основе вашего шаблона.

• 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. Создайте новое рабочее пространство для вашего шаблона, чтобы опубликовать и протестировать его. Если вы используете вложенный репозиторий, укажите прямую ссылку на него в вашем URL-адресе. Например, если вы используете шаблон сообщества "Vanilla Vite", вам нужно будет создать и протестировать новое рабочее пространство, используя следующий URL-адрес:

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

Перейдите к разделу «Настройка шаблона» , чтобы узнать о дополнительных изменениях, которые вы можете внести для его персонализации.

Настройте свой шаблон

Теперь, когда вы создали базовый шаблон, на основе которого можно строить дальнейшую работу, вы можете отредактировать файлы idx-template.json , idx-template.nix и .idx/dev.nix в соответствии с вашими требованиями. Возможно, вам также потребуется настроить дополнительные параметры:

• Добавьте системные пакеты в свой скрипт bootstrap .
• Добавить параметры, настраиваемые пользователем.
• Выберите, какие файлы должны открываться по умолчанию.
• Выберите значок рабочей области по умолчанию

Используйте дополнительные системные пакеты в вашем скрипте bootstrap .

В базовом примере для копирования файлов в нужное место используются только основные команды POSIX. Для запуска скрипта bootstrap вашего шаблона может потребоваться установка дополнительных исполняемых файлов, таких как git , node , python3 или другие.

Вы можете добавить дополнительные системные пакеты в свой скрипт загрузки, указав packages в файле idx-template.nix , точно так же, как вы настраиваете рабочую область, добавляя дополнительные системные пакеты packages файл dev.nix .

Вот пример добавления 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"
  ''
}

Добавить параметры, настраиваемые пользователем.

Чтобы пользователи могли настраивать отправную точку для своего нового проекта, вы можете либо создать несколько шаблонов, либо создать один шаблон с параметрами. Это отличный вариант, если ваши разные отправные точки — это просто разные значения, передаваемые в инструмент командной строки (например, --language=js против --language=ts ).

Для добавления параметров вам потребуется:

1. Опишите свой параметр в объекте params файла метаданных idx-template.json . Firebase Studio использует информацию из этого файла для подготовки пользовательского интерфейса (например, флажков, выпадающих списков и текстовых полей), отображаемого пользователям вашего шаблона.
2. Обновите файл idx-template.nix bootstrap, чтобы использовать значения, выбранные пользователем при создании экземпляра шаблона.

Опишите ваш параметр в 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), пользовательский интерфейс отобразит группу переключателей для этих двух вариантов и передаст в скрипт idx-template.nix либо значение ts , либо js .

Каждый объект параметра обладает следующими свойствами:

Используйте значения параметров в idx-template.nix

После определения объекта params в файле idx-template.json вы можете начать настраивать скрипт загрузки в соответствии со значениями параметров, выбранными пользователем.

Следуя примеру из предыдущего раздела, если у вас есть единственный параметр с идентификатором 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 !), добавив в него обработчик события onCreate с атрибутом openFiles , следующим образом:

# .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 = { ... };
  };
}

Выберите значок рабочей области по умолчанию

Вы можете выбрать значок по умолчанию для рабочих областей, созданных с помощью вашего шаблона, разместив файл PNG с именем icon.png рядом с файлом dev.nix в каталоге .idx .

Протестируйте свой шаблон в новом рабочем пространстве.

Простейший способ протестировать ваш шаблон от начала до конца — создать с ним новое рабочее пространство. Перейдите по следующей ссылке, заменив пример URL-адресом репозитория 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

Это также URL-адрес, которым вы поделитесь с другими, чтобы они могли использовать ваш новый шаблон, или URL-адрес, на который вы будете ссылаться с кнопки «Открыть в Firebase Studio » .

Поделитесь своим шаблоном

После того, как вы убедитесь, что ваш шаблон работает должным образом, опубликуйте его в репозитории GitHub и поделитесь той же ссылкой, которую вы использовали при создании рабочей области для тестирования .

А чтобы пользователям было еще проще найти ваш шаблон, добавьте кнопку «Открыть в Firebase Studio » в файл README вашего веб-сайта или репозитория.