Créer un modèle personnalisé

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

Vous pouvez également lancer un espace de travail Firebase Studio à l'aide des modèles Communauté hébergés sur GitHub. Pour savoir comment lancer un espace de travail à partir d'un modèle, consultez Créer un espace de travail Firebase Studio.

La plupart des utilisateurs utiliseront les modèles intégrés ou importeront des projets depuis 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 se familiariser rapidement avec 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 à l'aide d'un tutoriel ou d'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 pour le placer sur votre site Web, dans votre fichier README de dépôt Git, sur la page d'informations sur le package (par exemple, dans NPM) ou à tout autre endroit où vous pensez que vos utilisateurs commenceront à utiliser votre technologie.

Remarque : Vous pouvez également créer un lien permettant aux utilisateurs de créer un espace de travail en clonant un dépôt Git. Bien que cette méthode soit moins configurable que la création de votre propre modèle Firebase Studio, elle ne nécessite aucune modification du dépôt Git. Pour en savoir plus, consultez Créer un espace de travail.

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 un certain nombre de langages de programmation ou d'exemples d'utilisation. Firebase Studio utilise ces informations pour préparer l'UI 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 en langage Nix 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. Notez que vous pouvez également exécuter un outil d'échafaudage 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 dans 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 à côté de 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 d'échafaudage 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 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. Un sous-dossier .idx doit déjà exister 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 une branche), ce dépôt devient un modèle Firebase Studio.

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

Remarque : En plus de $out, vous pouvez également obtenir le nouvel ID d'espace de travail à l'aide de la variable $WS_NAME.

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

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

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

• Modèles officiels : il s'agit des modèles que vous sélectionnez directement dans le tableau de bord Firebase Studio 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.

  Conseil : Pour contribuer à la communauté en ajoutant des modèles ou en mettant à jour des modèles existants, envoyez une demande d'extraction.

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 Créer un espace de travail pour votre modèle pour publier et 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 utilisiez le modèle communautaire "Vanilla Vite", vous provisionneriez et testeriez 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
   

Consultez 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 appuyer, vous pouvez modifier les fichiers idx-template.json, idx-template.nix et .idx/dev.nix pour qu'ils correspondent à vos besoins. Vous pouvez personnaliser d'autres configurations :

• Ajoutez des packages système à votre script bootstrap.
• Ajouter des paramètres configurables par l'utilisateur
• Choisir les fichiers qui doivent s'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 les fichiers au bon endroit. Le script bootstrap de votre modèle peut nécessiter l'installation de binaires supplémentaires, tels que git, node, python3 ou d'autres.

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

Remarque : idx-template.nix utilise toujours le canal Nix stable-23.11.

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

Important : Votre script d'amorçage ne peut pas être interactif. Si le modèle attend une saisie de l'utilisateur, il ne pourra pas être instancié correctement.

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 :

1. Décrivez 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'UI (par exemple, les cases à cocher, les menus déroulants et les champs de texte) affichée aux utilisateurs de votre modèle.
2. Mettez à jour votre bootstrap idx-template.nix pour utiliser les valeurs sélectionnées par l'utilisateur lors de l'instanciation du modèle.

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

Voici un exemple d'ajout d'un paramètre enum, qui Firebase Studio s'affiche sous la forme d'un menu déroulant ou d'un groupe de boutons radio, selon le 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'UI affichera un groupe de boutons radio pour les deux options et transmettra la valeur ts ou js au script idx-template.nix.

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

PROPRIÉTÉ	TYPE	DESCRIPTION
id	string	ID unique du paramètre, semblable à un nom de variable.
nom	string	Nom à afficher pour ce paramètre.
type	string	Spécifie le composant d'interface utilisateur à utiliser pour ce paramètre et le type de données à transmettre au script d'amorçage. Les valeurs possibles sont les suivantes : "enum" : affiche un groupe de cases d'option ou un menu déroulant, et transmet un string au bootstrap. "boolean" : affiche une case à cocher et transmet true ou false "text" : affiche un champ de texte et transmet un string
options	object	Pour les paramètres enum, il s'agit des options à afficher aux utilisateurs. Par exemple, si les options sont {"js": "JavaScript", ...}, "JavaScript" s'affiche comme option. Lorsque l'utilisateur la sélectionne, la valeur de ce paramètre est js.
par défaut	string ou boolean	Définit la valeur initiale dans l'UI. Pour les paramètres enum, il doit s'agir de l'une des clés de options. Pour les paramètres boolean, la valeur doit être true ou false.
required	boolean	Indique que ce paramètre est obligatoire.

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 d'amorçage en fonction des valeurs de paramètres 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. Voici une autre façon d'écrire l'exemple précédent :

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

Important : N'oubliez pas de toujours générer un fichier .idx/dev.nix dans le répertoire $out dans le cadre de votre script bootstrap. Si l'environnement de l'espace de travail généré doit varier en fonction des paramètres configurés par l'utilisateur (par exemple, en incluant différents packages système ou en personnalisant le crochet onCreate), vous pouvez utiliser la manipulation de chaînes dans Nix ou appeler un moteur de modèles tel que jinja2.

Choisir les fichiers qui doivent s'ouvrir par défaut

Nous vous recommandons de personnaliser les fichiers qui doivent être ouverts pour modification lorsque de nouveaux espaces de travail sont créés avec votre modèle. Par exemple, si votre modèle est destiné à un site Web de base, vous pouvez ouvrir les fichiers HTML, JavaScript et CSS principaux.

Pour personnaliser les fichiers qui doivent s'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.

Remarque : Le fichier idx-template.json inclut également une propriété icon facultative, qui doit pointer vers une URL publique au format PNG ou SVG, le cas échéant. Ce champ n'est pas utilisé dans Firebase Studio, mais il le sera probablement à l'avenir, avec d'autres métadonnées de modèle.

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 éventuellement inclure une branche et un sous-dossier. Toutes les URL suivantes sont valides, à condition qu'elles 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 pour qu'ils puissent utiliser votre nouveau modèle, ou de l'URL vers laquelle vous redirigerez votre bouton "Ouvrir dans Firebase Studio".

---

Partager votre modèle

Une fois que vous avez vérifié 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 encore plus facilement votre modèle, ajoutez un bouton Ouvrir dans Firebase Studio au fichier README de votre site Web ou de votre dépôt.