Cómo crear una plantilla personalizada

IDX ofrece una amplia variedad de plantillas integradas que incluyen todos los archivos, paquetes de sistema (p.ej., compiladores) y extensiones que un usuario puede necesitar 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 permitir que los usuarios comiencen rápidamente a usar tu tecnología, sin salir del 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 de inicio de proyectos nuevos 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 tus estudiantes. Para ello, configura previamente el punto de partida del codelab como una plantilla personalizada.

Una vez que tengas una plantilla personalizada lista, puedes crear un vínculo para colocarla en tu sitio web, el archivo README del repositorio de Git, la página de detalles del paquete (p.ej., en NPM) o en otros lugares donde los usuarios puedan querer comenzar a usar tu tecnología.

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

Requisitos previos

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

Las plantillas también usan el lenguaje Unix, por lo que te recomendamos repasar algunos de los conceptos básicos o tenerlo a mano como 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 contiene 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 su nombre visible para el usuario, la descripción y los parámetros disponibles para que los usuarios la configuren. Por ejemplo, puedes permitir que los usuarios elijan entre 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 eligen crear un lugar de trabajo nuevo desde tu plantilla.

• idx-template.nix es un archivo escrito con el lenguaje Nix que contiene una secuencia de comandos de shell Bash (unida en 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 ejecutar una secuencia de comandos personalizada escrita en Go, Python, Node.js o algún otro lenguaje.

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

Se pueden incluir otros archivos junto con estos dos para usarlos en idx-template.nix a fin de crear una instancia de la plantilla. Por ejemplo, puedes incluir el archivo .idx/dev.nix final o incluso todos los archivos de andamiaje directamente en el repositorio.

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

Antes de entrar en detalles sobre cómo definir tu idx-template.json y idx-template.nix, es útil ver una plantilla de ejemplo básica que hace lo siguiente:

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

Agregar los siguientes archivos a cualquier repositorio público de GitHub (o subcarpeta o rama) convierte 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 con $WS_NAME.

Usa paquetes de sistema adicionales en la secuencia de comandos bootstrap

En el ejemplo anterior, solo se usan comandos básicos de POSIX para copiar archivos en el lugar correcto. Es posible que la secuencia de comandos bootstrap de tu plantilla requiera que se instalen objetos binarios adicionales, como git, node, python3 y otros.

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

Nota: idx-template.nix siempre usa el canal de nueve stable-23.11.

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 la entrada del usuario, no se podrá crear una instancia de la plantilla de forma correcta.

Agrega parámetros configurables por el usuario

Para permitir que los usuarios personalicen el punto de partida de su nuevo proyecto, puedes crear varias plantillas o una sola con parámetros. Esta es una gran opción si tus diferentes puntos de partida son solo valores diferentes que se pasan a una herramienta de la CLI (por ejemplo, --language=js frente a --language=ts).

Para agregar parámetros, debes hacer lo siguiente:

1. Describe el parámetro en el objeto params de tu archivo de metadatos idx-template.json. IDX usa la información de este archivo para preparar la IU (como las casillas de verificación, los menús desplegables y los campos de texto) que se mostrará 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

A continuación, se muestra 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
    }
  ]
}

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

Cada objeto de parámetro tiene las siguientes propiedades:

PROPIEDAD	MÁQUINA DE ESCRIBIR	DESCRIPCIÓN
id	string	El ID único del parámetro, similar al nombre de una variable.
name	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", ...}, se mostrará "JavaScript" como opción y, cuando se seleccione, el valor de este parámetro será js.
default	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 el archivo idx-template.json, puedes comenzar a personalizar la secuencia de comandos de arranque según los valores de los parámetros que elija el usuario.

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 valores posibles ts o js, puedes usarlo de la siguiente manera:

# 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 de forma condicional según el valor 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 que siempre debes producir un archivo .idx/dev.nix en el directorio $out como parte de la secuencia de comandos bootstrap. Si el entorno de trabajo generado necesita variar en función de los parámetros configurados por el usuario (p.ej., incluir diferentes paquetes de sistema o personalizar el hook onCreate), puedes usar la 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 se deben abrir para editar cuando se crean lugares de trabajo nuevos con tu plantilla. Por ejemplo, si tu plantilla es para un sitio web básico, es posible que desees abrir los archivos HTML, JavaScript y CSS principales.

Para personalizar qué archivos se deben abrir de forma predeterminada, actualiza el archivo .idx/dev.nix (no el archivo idx-template.nix) para incluir un hook de lugar 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 = { ... };
  };
}

Crea un lugar de trabajo nuevo desde tu plantilla

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

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 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 tu plantilla nueva, o la URL a la que te vincularás desde el botón "Abrir en IDX".

---

Comparte tu plantilla

Una vez que confirmes que tu plantilla se comporta como se espera, publícala en un repositorio de GitHub y comparte el mismo vínculo que usaste cuando creaste un lugar de trabajo para pruebas.

Además, para que los usuarios puedan encontrar tu plantilla con mayor facilidad, agrega un botón"Abrir en IDX" al archivo README de tu sitio web o repositorio.