Создайте собственный шаблон

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

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

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

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

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

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

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

Совет: Вы также можете создать ссылку для пользователей на создание новой рабочей области, клонировав репозиторий Git. Хотя это менее настраиваемо, чем создание собственного шаблона IDX, оно не требует внесения изменений в репозиторий Git. Узнайте больше в разделе «Создание рабочего пространства» .

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

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

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

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

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

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

• 

  Создание нового рабочего пространства на основе пользовательского шаблона

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

• idx-template.nix — это файл, написанный на языке Nix и содержащий сценарий оболочки Bash (завернутый в функцию Nix), отвечающий за:

  1. Создание рабочего каталога новой рабочей области.
  2. Настройка среды путем создания файла .idx/dev.nix . Обратите внимание, что вы также можете просто запустить в этом скрипте инструмент формирования леса проекта, например flutter create или npm init , или запустить собственный скрипт, написанный на Go, Python, Node.js или другом языке.

  Этот файл будет выполнен с параметрами, указанными пользователем , когда IDX загрузит шаблон.

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

Создайте стартовый шаблон

Чтобы ускорить создание шаблона, мы рекомендуем вам начать с одного из следующих методов создания шаблона IDX, который вы можете в дальнейшем настроить:

• Превратите любой общедоступный репозиторий GitHub в шаблон
• Используйте официальный шаблон или шаблон сообщества в качестве основы для своего шаблона.

Простой пример: превратите любой общедоступный репозиторий 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}
  '';
}

Примечание. Помимо $out , вы также можете получить идентификатор новой рабочей области, используя $WS_NAME .

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

Создайте собственный шаблон, используя официальный шаблон или шаблон сообщества.

Команда Project IDX поддерживает два репозитория для шаблонов IDX:

• Официальные шаблоны . Это шаблоны, которые вы выбираете непосредственно на панели управления IDX при создании нового приложения.

• Шаблоны сообщества . Эти шаблоны допускают внесение вкладов со стороны сообщества открытого исходного кода. Чтобы использовать шаблон сообщества, клонируйте репозиторий Git шаблонов сообщества. Вы можете использовать полную ссылку на шаблон, который хотите использовать.

  Совет: Чтобы внести свой вклад в сообщество, добавив новые шаблоны или обновив существующие, отправьте запрос на включение.

Чтобы создать собственный шаблон на основе существующего шаблона:

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

2. Настройте idx-template.json , idx-template.nix и .idx/dev.nix по мере необходимости, начиная с пункта Настройка вашего шаблона .

3. Проверьте изменения в своем репозитории.

4. Следуйте инструкциям по созданию новой рабочей области для вашего шаблона , чтобы развернуть и протестировать его. Если вы используете вложенный репозиторий, добавьте прямую ссылку на него в своем URL-адресе. Например, если вы использовали шаблон сообщества Vanilla Vite, вам нужно подготовить и протестировать новое рабочее пространство, используя следующий URL-адрес:

   https://idx.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 .

Примечание: idx-template.nix всегда использует канал Nix stable-23.11 .

Вот пример добавления 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 . IDX использует информацию из этого файла для подготовки пользовательского интерфейса (например, флажков, раскрывающихся списков и текстовых полей), отображаемого пользователям вашего шаблона.
2. Обновите загрузочный файл 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 .

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

СВОЙСТВО	ТИП	ОПИСАНИЕ
идентификатор	string	Уникальный идентификатор параметра, аналогичный имени переменной.
имя	string	Отображаемое имя для этого параметра.
тип	string	Указывает компонент пользовательского интерфейса, который будет использоваться для этого параметра, и тип данных, передаваемых в сценарий начальной загрузки. Допустимые значения: "enum" — показывает раскрывающийся список или группу переключателей и передает string в загрузочную программу. "boolean" — показывает флажок и передает true или false "text" — показывает текстовое поле и передает string
параметры	object	Для параметров enum это параметры, которые будут отображаться пользователям. Например, если параметрами являются {"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" }

Важно: Не забывайте всегда создавать файл .idx/dev.nix в каталоге $out как часть сценария bootstrap . Если сгенерированная среда рабочей области должна меняться в зависимости от настроенных пользователем параметров (например, включая различные системные пакеты или настройку перехватчика onCreate ), вы можете использовать манипуляции со строками в Nix или вызвать механизм шаблонов, такой как jinja2 .

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

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

Примечание. Файл idx-template.json также включает необязательное свойство icon , которое должно указывать на общедоступный URL-адрес PNG или SVG, если оно указано. Это поле не используется в 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-адрес, на который вы будете ссылаться с помощью кнопки «Открыть в IDX» .

---

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

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

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