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), который:Создает рабочий каталог для нового рабочего пространства.
Настраивает свою среду, создавая файл
.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-репозиторий шаблонов сообщества. Вы можете использовать полную ссылку на нужный шаблон.
Чтобы создать собственный шаблон на основе существующего шаблона:
Решите, какой шаблон использовать в качестве основы для вашего пользовательского шаблона, а затем клонируйте проект.
Настройте
idx-template.json
,idx-template.nix
и.idx/dev.nix
по мере необходимости, начиная с раздела Настройте свой шаблон .Проверьте изменения в вашем репозитории.
Следуйте инструкциям по созданию нового рабочего пространства для вашего шаблона , чтобы опубликовать и протестировать его. Если вы используете вложенный репозиторий, укажите прямую ссылку на него в вашем 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"
''
}
Добавить настраиваемые пользователем параметры
Чтобы пользователи могли настроить начальную точку для своего нового проекта, вы можете создать несколько шаблонов или один шаблон с параметрами. Это отличный вариант, если разные начальные точки — это просто разные значения, передаваемые в CLI-инструмент (например, --language=js
и --language=ts
).
Чтобы добавить параметры, вам необходимо:
- Опишите свой параметр в объекте
params
файла метаданныхidx-template.json
. Firebase Studio использует информацию из этого файла для подготовки пользовательского интерфейса (например, флажков, раскрывающихся списков и текстовых полей), отображаемого пользователям вашего шаблона. - Обновите загрузчик
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
.
Каждый объект параметра имеет следующие свойства:
СВОЙСТВО | ТИП | ОПИСАНИЕ |
---|---|---|
идентификатор | string | Уникальный идентификатор параметра, аналогичный имени переменной. |
имя | string | Отображаемое имя этого параметра. |
тип | string | Указывает компонент пользовательского интерфейса, используемый для этого параметра, и тип данных, передаваемых в скрипт начальной загрузки. Допустимые значения:
|
параметры | object | Для параметров enum это параметры, которые будут отображаться пользователям. Например, если options — это {"js": "JavaScript", ...} , в качестве параметра будет отображаться "JavaScript", а при выборе этого параметра значением будет js . |
по умолчанию | string или boolean | Задаёт начальное значение в пользовательском интерфейсе. Для параметров enum это должен быть один из ключей в options . Для boolean параметров это должно быть true или false . |
необходимый | boolean | Указывает, что этот параметр является обязательным. |
Использовать значения параметров в 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 репозитория.