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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Вы также можете запустить рабочее пространство Firebase Studio используя шаблоны Community , размещенные на 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 или даже включить все файлы scaffolding прямо в репозитории.

Создайте начальный шаблон

Чтобы ускорить создание шаблона, мы рекомендуем вам начать с одного из следующих методов создания шаблона 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/project-idx/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"
  ''
}

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

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

Чтобы добавить параметры, вам необходимо:

1. Опишите ваш параметр в объекте params вашего файла метаданных idx-template.json . 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

После определения объекта 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 репозитория.