Créer un modèle personnalisé

Firebase Studio propose un large éventail de modèles intégrés qui incluent tous les fichiers, packages système (compilateurs, par exemple), et extensions dont vous avez besoin pour commencer rapidement à utiliser un langage ou un framework.

Vous pouvez également lancer un espace de travail Firebase Studio à l'aide de modèles de la communauté hébergés sur GitHub. Pour en savoir plus sur le lancement d'un nouvel espace de travail à partir d'un modèle, consultez Créer un Firebase Studio espace de travail.

La plupart des utilisateurs utilisent les modèles intégrés ou importent des projets à partir de Git, mais pour des cas d'utilisation plus avancés, vous pouvez créer vos propres modèles :

• Si vous créez votre propre framework, bibliothèque ou service, vous pouvez permettre à vos utilisateurs de commencer rapidement à utiliser votre technologie sans jamais quitter le navigateur, grâce à toute la puissance d'une machine virtuelle basée sur le cloud.

• Si vous avez une pile technologique préférée pour vos projets, vous pouvez simplifier votre propre processus de démarrage de nouveaux projets avec un modèle personnalisé.

• Si vous enseignez à d'autres personnes, par exemple dans un tutoriel ou un atelier de programmation, vous pouvez supprimer certaines des étapes initiales pour vos élèves en préconfigurant le point de départ de votre atelier de programmation en tant que modèle personnalisé.

Une fois que vous avez créé et testé votre modèle personnalisé, vous pouvez créer un lien vers celui-ci et le placer sur votre site Web, dans le fichier README de votre dépôt Git , sur la page de détails du package (dans NPM, par exemple) ou à tout autre endroit où vous souhaitez que vos utilisateurs commencent à utiliser votre technologie.

Prérequis

Avant de commencer :

• Découvrez comment utiliser le fichier idx/dev.nix pour personnaliser votre environnement.

• Familiarisez-vous avec les bases du langage Nix et gardez la référence à portée de main.

Structure du fichier de modèle

Un modèle Firebase Studio est un dépôt Git public (ou un dossier ou une branche dans un dépôt) qui contient au moins deux fichiers :

• idx-template.json inclut les métadonnées du modèle, y compris son nom visible par l'utilisateur, sa description et les paramètres disponibles pour les utilisateurs afin de configurer le modèle. Par exemple, vous pouvez autoriser vos utilisateurs à choisir parmi plusieurs langages de programmation ou exemples de cas d'utilisation. Firebase Studio utilise ces informations pour préparer l'interface utilisateur affichée aux utilisateurs lorsqu'ils choisissent de créer un espace de travail à partir de votre modèle.

• idx-template.nix est un fichier écrit avec le Nix langage qui contient un script shell Bash (encapsulé dans une fonction Nix) qui :

  1. crée le répertoire de travail pour le nouvel espace de travail ;

  2. configure son environnement en créant un fichier .idx/dev.nix. Note que vous pouvez également exécuter un outil de scaffolding de projet tel que flutter create ou npm init dans ce script, ou exécuter un script personnalisé écrit en Go, Python, Node.js ou un autre langage.

     Ce fichier sera exécuté avec les paramètres spécifiés par l'utilisateur lorsque Firebase Studio chargera le modèle.

D'autres fichiers peuvent être inclus avec ces deux fichiers, pour être utilisés dans idx-template.nix, afin d'instancier le modèle. Par exemple, vous pouvez inclure le fichier .idx/dev.nix final, ou même inclure tous les fichiers de scaffolding directement dans le dépôt.

Créer un modèle de démarrage

Pour accélérer la création de modèles, nous vous recommandons de commencer par l'une des méthodes suivantes pour créer un modèle Firebase Studio que vous pourrez personnaliser davantage :

• Transformer n'importe quel dépôt GitHub public en modèle
• Utiliser un modèle officiel ou de la communauté comme base pour votre modèle

Exemple de base : transformer n'importe quel dépôt GitHub public en modèle

Avant d'entrer dans les détails de la définition de vos fichiers idx-template.json et idx-template.nix, il est utile de voir un exemple de modèle de base qui :

• ne contient aucun paramètre configurable par l'utilisateur ;
• copie tous les fichiers de votre dépôt de modèles (à l'exception des deux fichiers idx-template) dans l'espace de travail de l'utilisateur. Il doit déjà exister un sous-dossier .idx avec un fichier dev.nix qui définit l'environnement.

Si vous ajoutez les fichiers suivants à un dépôt GitHub public (ou à un sous-dossier ou branche), cela transforme effectivement ce dépôt en Firebase Studio modèle.

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

Passez à Personnaliser votre modèle pour découvrir d'autres modifications que vous pouvez apporter à votre modèle.

Créer un modèle personnalisé à l'aide d'un modèle officiel ou de la communauté

L'équipe Firebase Studio gère deux dépôts pour Firebase Studio modèles :

• Modèles officiels : il s'agit des modèles que vous sélectionnez directement dans le Firebase Studio tableau de bord lorsque vous créez une application.

• Modèles de la communauté: Ces modèles permettent les contributions de la communauté Open Source. Pour utiliser un modèle de la communauté, clonez le dépôt Git des modèles de la communauté. Vous pouvez utiliser le lien complet vers le modèle que vous souhaitez utiliser.

Pour créer un modèle personnalisé à partir d'un modèle existant :

1. Choisissez le modèle à utiliser comme base pour votre modèle personnalisé, puis clonez le projet.

2. Personnalisez idx-template.json, idx-template.nix, et .idx/dev.nix selon vos besoins, en commençant par Personnaliser votre modèle.

3. Validez les modifications dans votre dépôt.

4. Suivez la procédure décrite dans Créer un espace de travail pour votre modèle afin de publier et de tester votre modèle. Si vous utilisez un dépôt imbriqué, créez un lien direct vers celui-ci dans votre URL. Par exemple, si vous utilisez le modèle de la communauté "Vanilla Vite", vous provisionnez et testez un nouvel espace de travail à l'aide de l'URL suivante :

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

Passez à Personnaliser votre modèle pour découvrir d'autres modifications que vous pouvez apporter à votre modèle.

Personnaliser votre modèle

Maintenant que vous avez créé un modèle de base sur lequel vous pouvez vous appuyer, vous pouvez modifier les fichiers idx-template.json, idx-template.nix et .idx/dev.nix en fonction de vos besoins. Vous pouvez personnaliser des configurations supplémentaires :

• Ajouter des packages système à votre script bootstrap.
• Ajouter des paramètres configurables par l'utilisateur
• Choisir les fichiers à ouvrir par défaut
• Choisir une icône d'espace de travail par défaut

Utiliser des packages système supplémentaires dans votre script bootstrap

L'exemple de base n'utilise que des commandes POSIX de base pour copier des fichiers au bon endroit. Le script bootstrap de votre modèle peut nécessiter l'installation d'autres binaires, tels que git, node, python3 ou autres.

Vous pouvez rendre des packages système supplémentaires disponibles pour votre script bootstrap en spécifiant packages dans votre fichier idx-template.nix, tout comme vous personnaliserez un espace de travail avec des packages système supplémentaires en ajoutant au packages dans son fichier dev.nix.

Voici un exemple d'ajout de pkgs.nodejs, qui inclut des binaires tels que node, npx et 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"
  ''
}

Ajouter des paramètres configurables par l'utilisateur

Pour permettre aux utilisateurs de personnaliser le point de départ de leur nouveau projet, vous pouvez créer plusieurs modèles ou un seul modèle avec des paramètres. Il s'agit d'une excellente option si vos différents points de départ ne sont que des valeurs différentes transmises à un outil CLI (par exemple, --language=js par rapport à --language=ts).

Pour ajouter des paramètres, vous devez :

1. décrire votre paramètre dans l'objet params de votre fichier de métadonnées idx-template.json. Firebase Studio utilise les informations de ce fichier pour préparer l'interface utilisateur (cases à cocher, listes déroulantes et champs de texte, par exemple) affichée aux utilisateurs de votre modèle.
2. mettre à jour votre bootstrap idx-template.nix pour utiliser les valeurs sélectionnées par l'utilisateur lors de l'instanciation du modèle.

Décrire votre paramètre dans idx-template.json

Voici un exemple d'ajout d'un paramètre enum, que Firebase Studio affiche sous forme de menu déroulant ou de groupe de cases d'option, en fonction du nombre d'options :

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

Comme il existe deux valeurs (JavaScript et TypeScript), l'interface utilisateur affiche un groupe de cases d'option pour les deux options et transmet la valeur ts ou js au script idx-template.nix.

Chaque objet de paramètre possède les propriétés suivantes :

Utiliser les valeurs de paramètre dans idx-template.nix

Après avoir défini l'objet params dans votre fichier idx-template.json, vous pouvez commencer à personnaliser le script bootstrap en fonction des valeurs de paramètre choisies par l'utilisateur.

En suivant l'exemple de la section précédente, si vous avez un seul paramètre avec l'ID language qui est une énumération avec les valeurs possibles ts ou js, vous pouvez l'utiliser comme suit :

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

Un autre modèle courant consiste à inclure du contenu de manière conditionnelle en fonction de la valeur d'une chaîne. Une autre façon d'écrire l'exemple précédent est la suivante :

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

Choisir les fichiers à ouvrir par défaut

Il est judicieux de personnaliser les fichiers à ouvrir pour modification lorsque de nouveaux espaces de travail sont créés avec votre modèle. Par exemple, si votre modèle concerne un site Web de base, vous pouvez ouvrir les principaux fichiers HTML, JavaScript et CSS.

Pour personnaliser les fichiers à ouvrir par défaut, mettez à jour votre fichier .idx/dev.nix (et non votre fichier idx-template.nix !) pour inclure un hook d'espace de travail onCreate avec un attribut openFiles, comme suit :

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

Choisir une icône d'espace de travail par défaut

Vous pouvez choisir l'icône par défaut pour les espaces de travail créés avec votre modèle en plaçant un fichier PNG nommé icon.png à côté du fichier dev.nix, dans le répertoire .idx.

Tester votre modèle dans un nouvel espace de travail

Le moyen le plus simple de tester votre modèle de bout en bout consiste à créer un espace de travail avec celui-ci. Accédez au lien suivant, en remplaçant l'exemple par l'URL du dépôt GitHub de votre modèle :

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

Vous pouvez également inclure une branche et un sous-dossier. Tous les éléments suivants sont valides, à condition qu'ils soient accessibles au public :

• 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

Il s'agit également de l'URL que vous partagerez avec d'autres utilisateurs afin qu'ils puissent utiliser votre nouveau modèle, ou de l'URL vers laquelle vous créerez un lien à partir de votre "Ouvrir dans Firebase Studio" bouton.

Partager votre modèle

Une fois que vous avez confirmé que votre modèle se comporte comme prévu, publiez-le dans un dépôt GitHub et partagez le même lien que celui que vous avez utilisé lors de la création d'un espace de travail pour les tests.

Pour permettre aux utilisateurs de trouver plus facilement votre modèle, ajoutez un "Ouvrir dans Firebase Studio" bouton à votre site Web ou au fichier README de votre dépôt.