Cómo crear una plantilla personalizada

Firebase Studio ofrece una amplia variedad de plantillas integradas que incluyen todos los archivos, los paquetes del sistema (por ejemplo, los compiladores) y las extensiones que necesitas para comenzar a usar un lenguaje o un framework rápidamente.

También puedes iniciar un espacio de trabajo de Firebase Studio con las plantillas de la Comunidad alojadas en GitHub. Para obtener más información sobre cómo iniciar un nuevo lugar de trabajo desde una plantilla, consulta Crea un lugar de trabajo de Firebase Studio.

La mayoría de los usuarios usarán las plantillas integradas o importarán proyectos desde Git, pero para casos de uso más avanzados, puedes crear tus propias plantillas:

• Si compiles tu propio framework, biblioteca o servicio, puedes permitir que los usuarios comiencen a usar tu tecnología rápidamente 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 para iniciar proyectos nuevos con una plantilla personalizada.

• Si enseñas a otras personas, por ejemplo, a través de un instructivo o un codelab, puedes quitar algunos de los pasos iniciales para tus estudiantes configurando previamente el punto de partida del codelab como una plantilla personalizada.

Después de crear y probar tu plantilla personalizada, puedes crear un vínculo para ella y colocarlo en tu sitio web, en el archivo README del repositorio de GitHub, en la página de detalles del paquete (por ejemplo, en NPM) o en cualquier otro lugar en el que esperes que tus usuarios comiencen a usar tu tecnología.

Requisitos previos

Antes de comenzar:

• Obtén información para usar el archivo idx/dev.nix y personalizar tu entorno.

• Familiarízate con los aspectos básicos del lenguaje Nix y ten a mano la referencia.

Estructura del archivo de plantilla

Una plantilla Firebase Studio es un repositorio público de Git (o una carpeta o una rama en un repositorio) que contiene al menos dos archivos:

• idx-template.json incluye los metadatos de la plantilla, como su nombre visible para el usuario, su descripción y los parámetros disponibles para que los usuarios configuren la plantilla. Por ejemplo, puedes permitir que los usuarios elijan entre varios lenguajes de programación o casos de uso de ejemplo. Firebase Studio usa esta información para preparar la IU que se muestra a los usuarios cuando eligen crear un lugar de trabajo nuevo a partir de tu plantilla.

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

  1. Crea el directorio de trabajo para el lugar de trabajo nuevo.

  2. Para configurar su entorno, crea un archivo .idx/dev.nix. Ten en cuenta que también puedes ejecutar una herramienta de andamiaje de proyectos, como flutter create o npm init, en esta secuencia de comandos, o bien ejecutar una secuencia de comandos personalizada escrita en Go, Python, Node.js o cualquier otro lenguaje.

     Este archivo se ejecutará con los parámetros que especifique el usuario cuando Firebase Studio cargue la plantilla.

Se pueden incluir otros archivos junto con estos dos para usarlos en idx-template.nix y 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.

Crea una plantilla inicial

Para acelerar la creación de plantillas, te recomendamos que comiences con uno de los siguientes métodos para crear una plantilla Firebase Studio que puedas personalizar más adelante:

• Convierte cualquier repositorio público de GitHub en una plantilla
• Usa una plantilla oficial o de la comunidad como base para tu plantilla

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

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

• No contiene parámetros configurables por el usuario.
• 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.

Si agregas los siguientes archivos a cualquier repositorio público de GitHub (o subcarpeta o rama), este se convierte en una plantilla Firebase Studio efectiva.

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

Continúa con Personaliza tu plantilla para obtener información sobre los cambios adicionales que puedes realizar para personalizarla.

Crea una plantilla personalizada con una plantilla oficial o de la comunidad

El equipo de Firebase Studio mantiene dos repositorios para las plantillas de Firebase Studio:

• Plantillas oficiales: Estas son las plantillas que seleccionas directamente desde el panel de Firebase Studio cuando creas una app nueva.

• Plantillas de la comunidad: Estas plantillas permiten contribuciones de la comunidad de código abierto. Para usar una plantilla de la comunidad, clona el repositorio de Git de plantillas de la comunidad. Puedes usar el vínculo completo a la plantilla que deseas usar.

Para crear una plantilla personalizada con una plantilla existente como base, sigue estos pasos:

1. Decide qué plantilla usar como base para tu plantilla personalizada y, luego, clona el proyecto.

2. Personaliza idx-template.json, idx-template.nix y .idx/dev.nix según sea necesario, comenzando con Personaliza tu plantilla.

3. Verifica los cambios en tu repositorio.

4. Sigue las instrucciones de Cómo crear un lugar de trabajo nuevo para tu plantilla para publicar y probar tu plantilla. Si usas un repositorio anidado, vincúlalo directamente en tu URL. Por ejemplo, si usaras la plantilla de la comunidad "Vanilla Vite", aprovisionarías y probarías un nuevo espacio de trabajo con la siguiente URL:

   https://studio.firebase.google.com/new?template=https://github.com/project-idx/community-templates/tree/main/vite-vanilla
   

Continúa con Personaliza tu plantilla para obtener información sobre los cambios adicionales que puedes realizar para personalizarla.

Personaliza tu plantilla

Ahora que creaste una plantilla básica para basarte, puedes editar los archivos idx-template.json, idx-template.nix y .idx/dev.nix para que coincidan con tus requisitos. Te recomendamos que personalices los siguientes parámetros de configuración:

• Agrega paquetes del sistema a tu secuencia de comandos bootstrap.
• Cómo agregar parámetros configurables por el usuario
• Elige qué archivos se deben abrir de forma predeterminada
• Elige un ícono de lugar de trabajo predeterminado

Usa paquetes del sistema adicionales en tu secuencia de comandos bootstrap

En el ejemplo básico, solo se usan comandos POSIX básicos 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.

Para que los paquetes del sistema adicionales estén disponibles para tu secuencia de comandos de inicio, especifica packages en tu archivo idx-template.nix, del mismo modo que personalizarías un espacio de trabajo con paquetes del sistema adicionales agregando packages a su archivo dev.nix.

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

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 plantilla con parámetros. Esta es una excelente opción si tus diferentes puntos de partida son solo diferentes valores que se pasan a una herramienta de CLI (por ejemplo, --language=js en comparación con --language=ts).

Para agregar parámetros, sigue estos pasos:

1. Describe tu parámetro en el objeto params de tu archivo de metadatos idx-template.json. Firebase Studio 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 muestra a los usuarios de tu plantilla.
2. Actualiza tu arranque idx-template.nix para usar los valores que seleccionó el usuario mientras creaba 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 Firebase Studio 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 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:

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

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

Siguiendo 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" }

Elige qué archivos se deben abrir de forma predeterminada

Es recomendable personalizar los archivos que se deben abrir para editarlos cuando se crean nuevos espacios de trabajo con tu plantilla. Por ejemplo, si tu plantilla es para un sitio web básico, te recomendamos que abras los archivos HTML, JavaScript y CSS principales.

Para personalizar los archivos que 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 = { ... };
  };
}

Elige un ícono de lugar de trabajo predeterminado

Para elegir el ícono predeterminado de los lugares de trabajo creados con tu plantilla, coloca un archivo PNG llamado icon.png junto al archivo dev.nix, dentro del directorio .idx.

Prueba tu plantilla en un lugar de trabajo nuevo

La forma más sencilla de probar tu plantilla de extremo a extremo es crear un espacio 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. Todos los siguientes son válidos, siempre que se pueda acceder a ellos de forma pública:

• 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 otras personas para que puedan usar tu nueva plantilla, o la URL a la que vincularás desde el botón “Abrir en Firebase Studio”.

Cómo compartir tu plantilla

Después de confirmar 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 espacio de trabajo para pruebas.

Además, para que los usuarios puedan encontrar tu plantilla con mayor facilidad, agrega un botón “Abrir en Firebase Studio” a tu sitio web o al archivo README del repositorio.