Créer un modèle personnalisé

IDX propose une large gamme de modèles intégrés qui incluent tous les fichiers, packages système (compilateurs, par exemple) et extensions dont un utilisateur peut avoir besoin pour commencer rapidement à utiliser un langage ou un framework.

Vous pouvez également créer vos propres modèles configurables par l'utilisateur. Exemple :

• Si vous créez votre propre framework, bibliothèque ou service, vous pouvez permettre à vos utilisateurs de se familiariser rapidement avec votre technologie, sans quitter le navigateur, en profitant de toute la puissance d'une machine virtuelle dans 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 aux autres participants, par exemple via un atelier de programmation, vous pouvez supprimer certaines é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 disposez d'un modèle personnalisé, vous pouvez créer un lien à placer sur votre site Web, le fichier README du dépôt Git, la page d'informations du package (par exemple, dans NPM) ou à d'autres emplacements à partir desquels les utilisateurs peuvent souhaiter commencer à 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. Cette méthode est moins configurable que la création de votre propre modèle IDX, mais elle ne nécessite aucune modification du dépôt Git.

Conditions préalables

Avant de commencer, assurez-vous d'être familiarisé avec la personnalisation de votre environnement avec des fichiers .idx/dev.nix.

Les modèles utilisent également le langage Nix. Vous pouvez donc revoir certains principes de base ou le garder à portée de main comme référence.

Structure du fichier de modèle

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

• 

  Créer un espace de travail à partir d'un modèle personnalisé

  idx-template.json inclut les métadonnées du modèle, y compris son nom, sa description et les paramètres que les utilisateurs peuvent voir pour le configurer. Par exemple, vous pouvez permettre à vos utilisateurs de choisir parmi un certain nombre de langages de programmation ou d'exemples de cas d'utilisation. IDX utilise ces informations pour préparer l'interface utilisateur présenté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 langage Nix qui contient un script shell bash (encapsulé dans une fonction Nix) chargé:

  1. Créer le répertoire de travail du nouvel espace de travail
  2. Configurer son environnement en créant un fichier .idx/dev.nix Notez que vous pouvez également simplement exécuter un outil d'échafaudage de projet comme 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 lors de la configuration du modèle.

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

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

Avant d'examiner en détail comment définir vos idx-template.json et idx-template.nix, il est utile de consulter un exemple de modèle de base qui:

• Aucun paramètre configurable par l'utilisateur
• Il suffit de copier tous les fichiers du 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à y avoir un sous-dossier .idx avec un fichier dev.nix définissant l'environnement.

L'ajout des fichiers suivants à un dépôt GitHub public (ou à un sous-dossier ou à une branche) le transforme efficacement en modèle 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}
  '';
}

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

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

L'exemple précédent n'utilise que les commandes POSIX de base pour copier des 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, etc.

Vous pouvez mettre des packages système supplémentaires à la disposition de votre script d'amorçage en spécifiant packages dans votre fichier idx-template.nix, comme vous le feriez pour personnaliser 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. S'il attend l'entrée utilisateur, l'instanciation du modèle échouera 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 d'interface de ligne de commande (par exemple, --language=js et --language=ts).

Pour ajouter des paramètres, procédez comme suit:

1. Décrivez votre paramètre dans l'objet params de votre fichier de métadonnées idx-template.json. IDX utilise les informations de ce fichier pour préparer l'interface utilisateur (comme les cases à cocher, les listes déroulantes et les champs de texte) présentée aux utilisateurs de votre modèle.
2. Mettez à jour votre amorçage 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, qu'IDX affiche sous la forme d'un menu déroulant ou d'un 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
    }
  ]
}

Étant donné qu'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:

PROPRIÉTÉ	MACH	DESCRIPTION
id	string	ID unique du paramètre, semblable à un nom de variable.
name	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 menu déroulant ou un groupe de cases d'option, et transmet un string à l'amorçage "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 à proposer aux utilisateurs. Par exemple, si l'option est définie sur {"js": "JavaScript", ...}, l'option "JavaScript" est affichée. Lorsqu'elle est sélectionnée, la valeur de ce paramètre est js.
par défaut	string ou boolean	Définit la valeur initiale dans l'interface utilisateur. 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.
sans nécessiter de provisionnement.	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ètre choisies par l'utilisateur.

Pour reprendre 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:

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 d'espace de travail généré doit varier en fonction des paramètres configurés par l'utilisateur (par exemple, inclure différents packages système ou personnaliser le hook onCreate), vous pouvez utiliser la manipulation de chaîne dans Nix ou faire appel à un moteur de création de modèles tel que jinja2.

Choisissez les fichiers à ouvrir par défaut

Il est judicieux de personnaliser les fichiers à ouvrir pour modification lorsque des espaces de travail sont créés avec votre modèle. Par exemple, si votre modèle est destiné à un site Web basique, vous souhaiterez peut-être ouvrir les principaux fichiers HTML, JavaScript et CSS.

Pour personnaliser les fichiers à ouvrir par défaut, mettez à jour votre fichier .idx/dev.nix (pas votre fichier idx-template.nix) afin d'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 = { ... };
  };
}

Créer un espace de travail à partir de votre modèle

Le moyen le plus simple de tester votre modèle de bout en bout consiste à créer un espace de travail à l'aide de 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. Tous les éléments suivants sont valides, du moment qu'ils sont 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 redirigerez les utilisateurs à l'aide du bouton "Ouvrir dans IDX".

---

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 vous avez utilisé lors de la création d'un espace de travail à des fins de test.

Pour que les utilisateurs trouvent encore plus facilement votre modèle, ajoutez un bouton"Ouvrir dans IDX" au fichier README de votre site Web ou de votre dépôt.