Créer un modèle personnalisé

IDX propose un large éventail d'outils intégrés modèles qui incluent tous les fichiers, le système les packages (compilateurs, par exemple) et les extensions qu'un utilisateur peut avoir besoin de se lancer rapidement avec 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 : pour permettre à vos utilisateurs de se familiariser rapidement avec votre technologie, sans en quittant le navigateur, en exploitant 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 quelques-unes des premières étapes pour vos élèves en préconfigurant de votre atelier de programmation en tant que modèle personnalisé.

Une fois que votre modèle personnalisé est prêt, vous pouvez créer un lien vers Il à placer sur votre site Web, dans le dépôt Git README la page d'informations du package (par exemple, dans GPR), ou à d'autres emplacements à partir desquels les utilisateurs peuvent vous souhaitez commencer à utiliser votre technologie.

Remarque :Vous pouvez également créer un lien permettant aux utilisateurs de créer un espace de travail en le clonant. un dépôt Git, ce qui est moins configurable que de créer votre propre IDX. sans modifier le dépôt Git.

Prérequis

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 devrez donc peut-être rafraîchir vos connaissances de base ou le garder à portée de main 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). contenant au moins deux fichiers:

• <ph type="x-smartling-placeholder">

  </ph> <ph type="x-smartling-placeholder">

  </ph> 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 ses paramètres visibles par l'utilisateur, configurer le modèle. Par exemple, vous pouvez autoriser vos utilisateurs à choisir entre un certain nombre de langages de programmation ou des 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 nouvel espace de travail à partir de votre modèle.

• idx-template.nix est un fichier écrit avec l'API Nix contenant un shell bash (encapsulé dans une fonction Nix) responsable de:

  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 aussi simplement exécuter un outil d'échafaudage (scaffolding) de projet comme 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. lors de la configuration du modèle.

D'autres fichiers peuvent être inclus en plus de ces deux fichiers, pour une utilisation 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 l'ensemble de l'échafaudage 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, consultez un exemple de modèle de base qui:

• Aucun paramètre configurable par l'utilisateur
• Il copie simplement tous les fichiers du dépôt de modèles (sauf les deux idx-template) dans l'espace de travail de l'utilisateur. Il doit déjà y avoir Sous-dossier .idx avec un fichier dev.nix définissant l'environnement.

Ajouter les fichiers suivants à n'importe quel dépôt public GitHub (ou sous-dossier ou branche) transforme efficacement ce dépôt 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 en utilisant $WS_NAME.

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

L'exemple précédent n'utilise les commandes POSIX de base que pour copier des fichiers dans la partie droite à un emplacement. Le script bootstrap de votre modèle peut nécessiter que des binaires supplémentaires soient installés, comme git, node, python3, etc.

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

Remarque :idx-template.nix utilise toujours la stable-23.11 Nix de votre chaîne.

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 que l'utilisateur l'instanciation correcte du modèle échouera.

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 vous pouvez soit créer plusieurs modèles, soit créer un seul modèle avec des paramètres. C'est une excellente option si vos points de départ sont différents. transmises à un outil CLI (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 idx-template.json. fichier de métadonnées. IDX utilise les informations de ce fichier pour préparer l'UI (cases à cocher, listes déroulantes et champs de texte, par exemple) présentées aux utilisateurs modèle.
2. Mettez à jour votre démarrage 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 comme un menu déroulant ou un groupe de cases d'option, selon le nombre d'options disponibles :

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

Puisqu'il existe deux valeurs (JavaScript et TypeScript), l'interface utilisateur affichera une groupe de cases d'option pour les deux options et transmettez la valeur ts ou js à le 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.
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 valides 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 {"js": "JavaScript", ...}, "JavaScript" est affichée en tant qu'option. 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.
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 Commencez à personnaliser le script d'amorçage en fonction des valeurs de paramètre que l'utilisateur choisit.

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

# 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 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 $out dans votre script bootstrap. Si l'espace de travail généré doit varier en fonction des paramètres configurés par l'utilisateur (par exemple, différents packages système ou personnaliser le hook onCreate), vous pouvez utiliser manipulation de chaînes 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 des espaces de travail sont créés avec votre modèle. Par exemple, si votre modèle est destiné un site Web basique, 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 (pas votre fichier idx-template.nix) pour inclure un hook d'espace de travail onCreate. avec un attribut openFiles, comme ceci:

# .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, à l'intérieur de .idx.

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

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 avec lui. Consultez le lien suivant, en remplaçant l'exemple par le code de votre URL du dépôt GitHub:

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, tant qu'elles sont accessibles publiquement:

• 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 les autres utilisateurs afin qu'ils puissent utiliser votre nouvelle ou l'URL de destination de votre "Ouvrir dans IDX" bouton.

---

Partager votre modèle

Après avoir vérifié que votre modèle se comporte comme prévu, publiez-le GitHub et partagez le lien que vous avez utilisé pour créer un espace de travail à des fins de test.

Et pour que les utilisateurs trouvent encore plus facilement votre modèle, ajoutez un bouton "Ouvrir dans IDX&quot; vers le fichier README de votre site Web ou de votre dépôt.