Cómo crear una plantilla personalizada

IDX ofrece una amplia gama de dispositivos plantillas que incluyen todos los archivos, paquetes (p.ej., compiladores) y extensiones que un usuario puede necesitas para comenzar rápidamente a usar un lenguaje o framework.

También puedes crear tus propias plantillas configurables por el usuario. Por ejemplo:

• Si estás compilando tu propio framework, biblioteca o servicio, puedes para que los usuarios comiencen a usar tu tecnología rápidamente, sin abandonando el navegador, con toda la potencia de una máquina virtual basada en la nube.

• Si tienes una pila de tecnología preferida para tus proyectos, puedes simplificar tu propio proceso para comenzar nuevos proyectos con una plantilla personalizada.

• Si enseñas a otras personas, como a través de un codelab, puedes quitar algunos de los pasos iniciales para los estudiantes configurando de tu codelab como una plantilla personalizada.

Una vez que tengas una plantilla personalizada lista, puedes crear un vínculo para para colocarlo en tu sitio web, repositorio de Git README la página de detalles del paquete (por ejemplo, en NPM) u otros lugares desde donde los usuarios quieren comenzar a usar la tecnología.

Nota: También puedes crear un vínculo para que los usuarios creen un lugar de trabajo nuevo mediante la clonación un repositorio de Git, que es menos configurable que crear tu propio IDX plantilla, pero no requiere cambios en el repositorio de Git.

Requisitos previos

Antes de comenzar, asegúrate de estar familiarizado con la personalización de tus entorno con archivos .idx/dev.nix.

Las plantillas también usan el lenguaje Unix, por lo que recomendamos repasar algunos de los conceptos básicos o tenerlo a mano referencia.

Estructura de archivos de la plantilla

Una plantilla es un repositorio público de GitHub (o una carpeta o rama de un repositorio) que contenga al menos dos archivos:

• 

  Crea un lugar de trabajo nuevo a partir de una plantilla personalizada

  idx-template.json incluye los metadatos de la plantilla, incluidos los siguientes: su nombre visible para el usuario, la descripción y los parámetros disponibles para los usuarios configurar la plantilla. Por ejemplo, puedes permitir que los usuarios elijan con varios lenguajes de programación o ejemplos de casos de uso. IDX usa esta información para preparar la IU que se muestra a los usuarios cuando deciden crear un nuevo lugar de trabajo desde tu plantilla.

• idx-template.nix es un archivo escrito con el protocolo Nix lenguaje que contiene una shell Bash secuencia de comandos (dentro de una función Nix) responsable de lo siguiente:

  1. Crea el directorio de trabajo del nuevo lugar de trabajo y
  2. La configuración de su entorno mediante la creación de un archivo .idx/dev.nix Ten en cuenta que también puedes ejecutar una herramienta de andamiaje del proyecto como flutter create o npm init en esta secuencia de comandos o ejecuta una personalizada escrita en Go o Python. Node.js o algún otro lenguaje.

  Este archivo se ejecutará con los parámetros especificados por el usuario cuando configuraron la plantilla.

Se pueden incluir otros archivos junto con estos dos para su uso en idx-template.nix, para crear una instancia de la plantilla Por ejemplo, podrías Incluye el archivo .idx/dev.nix final o incluso incluye todo el andamiaje. directamente en el repositorio.

Ejemplo básico: Convierte cualquier repositorio público de GitHub en una plantilla

Antes de entrar en los detalles sobre cómo definir tu idx-template.json y idx-template.nix, es útil ver una plantilla de ejemplo básica con las siguientes características:

• No tiene parámetros configurables por el usuario
• Simplemente copia todos los archivos de tu repositorio de plantillas (excepto los dos idx-template) en el espacio de trabajo del usuario. Ya debería haber un Subcarpeta .idx con un archivo dev.nix que define el entorno.

Agregar los siguientes archivos a cualquier repositorio público de GitHub (o subcarpetas ) convierte eficazmente ese repositorio en una plantilla de 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}
  '';
}

Nota: Además de $out, también puedes obtener el ID del lugar de trabajo nuevo usando $WS_NAME.

Usa paquetes de sistema adicionales en la secuencia de comandos bootstrap

En el ejemplo anterior, solo se usan comandos POSIX básicos para copiar archivos en el en un lugar específico. Es posible que la secuencia de comandos bootstrap de tu plantilla requiera que se usen objetos binarios adicionales instaladas, como git, node, python3 y otras.

Puedes hacer que los paquetes del sistema adicionales estén disponibles para tu secuencia de comandos de arranque haciendo lo siguiente: especificando packages en tu archivo idx-template.nix, como lo harías personaliza un lugar de trabajo con paquetes de sistema adicionales si agregas packages en su archivo dev.nix.

Nota: idx-template.nix siempre usa stable-23.11 Nix canal.

Este es un ejemplo de cómo agregar pkgs.nodejs, que incluye objetos binarios como node, npx y 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"
  ''
}

Importante: La secuencia de comandos de arranque no puede ser interactiva. Si espera a que el usuario entrada, la plantilla no podrá crear una instancia correcta.

Agrega parámetros configurables por el usuario

Para permitir que los usuarios personalicen el punto de partida de su nuevo proyecto, puedes Puede crear varias plantillas o una sola con parámetros. Esta es una excelente opción si los distintos puntos de partida son simplemente diferentes. valores pasados a una herramienta de la CLI (por ejemplo, --language=js en comparación con --language=ts).

Para agregar parámetros, debes hacer lo siguiente:

1. Describe tu parámetro en el objeto params de tu idx-template.json en un archivo de metadatos. IDX usa la información de este archivo para preparar la IU (como casillas de verificación, menús desplegables y campos de texto) que se muestran a los usuarios de tu plantilla.
2. Actualiza el arranque de idx-template.nix para usar los valores que seleccionó el usuario mientras se crea una instancia de la plantilla.

Describe tu parámetro en idx-template.json

Este es un ejemplo de cómo agregar un parámetro enum, que IDX muestra como un menú desplegable o un grupo de botones de selección, según la cantidad de opciones.

{
  "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
    }
  ]
}

Como existen dos valores (JavaScript y TypeScript), la IU renderizará un grupo de botones de selección para las dos opciones y pasa el valor ts o js a la secuencia de comandos idx-template.nix.

Cada objeto de parámetro tiene las siguientes propiedades:

PROPIEDAD	TIPO	DESCRIPCIÓN
id	string	El ID único del parámetro, similar al nombre de una variable.
nombre	string	El nombre visible de este parámetro.
tipo	string	Especifica el componente de IU que se usará para este parámetro y el tipo de datos que se pasará a la secuencia de comandos de arranque. Estos son los valores válidos: "enum": Muestra un grupo de botones de selección o menú desplegable y pasa un string al arranque. "boolean": Muestra una casilla de verificación y pasa true o false. "text": Muestra un campo de texto y pasa un string.
opciones	object	Para los parámetros enum, representa las opciones que se mostrarán a los usuarios. Por ejemplo, si las opciones son {"js": "JavaScript", ...}, "JavaScript" Se mostrará como la opción y, cuando se seleccione, el valor de este parámetro será js.
predeterminado	string o boolean	Establece el valor inicial en la IU. Para los parámetros enum, esta debe ser una de las claves en options. Para los parámetros boolean, debe ser true o false.
obligatorio	boolean	Indica que este parámetro es obligatorio.

Usa valores de parámetros en idx-template.nix

Después de definir el objeto params en tu archivo idx-template.json, puedes Comienza a personalizar la secuencia de comandos de arranque según los valores de los parámetros que el usuario elige.

Según el ejemplo de la sección anterior, si tienes un solo parámetro con el ID language, que es una enumeración con posibles valores ts o js, puedes usar así:

# 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}
  ''
}

Otro patrón común es incluir contenido condicionalmente según el de una cadena. Otra forma de escribir el ejemplo anterior es la siguiente:

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

Importante: Recuerda producir siempre un .idx/dev.nix archivo en la $out como parte de la secuencia de comandos bootstrap. Si el espacio de trabajo generado debe variar según los parámetros configurados por el usuario (p.ej., diferentes paquetes de sistema o personalizando el hook onCreate), puedes usar manipulación de cadenas en Nix o llamar a un motor de plantillas, como jinja2.

Elige los archivos que se deben abrir de forma predeterminada

Es una buena idea personalizar qué archivos deben abrirse para su edición cuando hay nuevos espacios de trabajo se crean con tu plantilla. Por ejemplo, si tu plantilla es para un sitio web básico, abre los archivos HTML, JavaScript y CSS principales.

Para personalizar qué archivos se deben abrir de forma predeterminada, actualiza tu archivo .idx/dev.nix (no tu archivo idx-template.nix) para incluir un hook de espacio de trabajo onCreate con un atributo openFiles, de la siguiente manera:

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

Elige un ícono de lugar de trabajo predeterminado

Puedes elegir el ícono predeterminado para los lugares de trabajo creados con tu plantilla. colocando un archivo PNG llamado icon.png junto al archivo dev.nix, dentro de .idx.

Nota: El archivo idx-template.json también incluye una propiedad icon opcional. que debe dirigir a una URL pública en formato PNG o SVG, cuando se proporciona. Este campo no es utilizados en IDX, pero que es probable que se utilicen en el futuro, junto con otras metadatos de plantilla.

Crea un lugar de trabajo nuevo desde tu plantilla

La forma más sencilla de probar la plantilla de extremo a extremo es crear un nuevo lugar de trabajo con él. Visita el siguiente vínculo y reemplaza el ejemplo por el de tu plantilla. URL del repositorio de GitHub:

https://idx.google.com/new?template=https://github.com/my-org/my-repo

De manera opcional, puedes incluir una rama y una subcarpeta. Todas las siguientes opciones son son válidas, siempre que sean de acceso público:

• 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

Esta también es la URL que compartirás con otros para que puedan usar la nueva plantilla o la URL a la que te vincularás desde tu pestaña "Abrir en IDX" de la aplicación.

---

Comparte tu plantilla

Cuando confirmes que tu plantilla se comporta según lo esperado, publícala en un repositorio de GitHub y comparte el mismo vínculo que usaste cuando creaste un lugar de trabajo para realizar pruebas.

Y para que los usuarios encuentren tu plantilla aún más fácilmente, agrega una ventana "Abrir en IDX” botón a tu sitio web o repositorio README.