Benutzerdefinierte Vorlage erstellen

IDX bietet eine breite Palette integrierter Vorlagen, die alle Dateien, Systempakete (z.B. Compiler) und Erweiterungen enthalten, die ein Nutzer für den schnellen Einstieg in eine Sprache oder ein Framework benötigt.

Sie können auch eigene, vom Nutzer konfigurierbare Vorlagen erstellen. Beispiel:

• Wenn Sie ein eigenes Framework, eine eigene Bibliothek oder einen eigenen Dienst erstellen, können Sie es Ihren Nutzern ermöglichen, mit der vollen Leistung einer cloudbasierten virtuellen Maschine schnell mit Ihrer Technologie zu beginnen, ohne den Browser zu verlassen.

• Wenn Sie einen bevorzugten Technology Stack für Ihre Projekte haben, können Sie Ihren eigenen Prozess zum Starten neuer Projekte mit einer benutzerdefinierten Vorlage vereinfachen.

• Wenn Sie andere Lehrkräfte unterrichten, z. B. über ein Codelab, können Sie einige der anfänglichen Schritte für Ihre Schüler entfernen. Dazu konfigurieren Sie den Ausgangspunkt für Ihr Codelab als benutzerdefinierte Vorlage vor.

Sobald Sie eine benutzerdefinierte Vorlage erstellt haben, können Sie einen Link erstellen, den Sie auf Ihrer Website, in der Git-Repository-Datei README, auf der Seite mit den Paketdetails (z.B. in NPM) oder an anderen Stellen einfügen können, an denen Nutzer mit Ihrer Technologie beginnen möchten.

Hinweis: Sie können auch einen Link erstellen, über den Nutzer einen neuen Arbeitsbereich erstellen, indem Sie ein Git-Repository klonen. Dies ist weniger konfigurierbar als das Erstellen Ihrer eigenen IDX-Vorlage, erfordert aber keine Änderungen am Git-Repository.

Voraussetzungen

Bevor Sie beginnen, sollten Sie sich mit der Anpassung Ihrer Umgebung mit .idx/dev.nix-Dateien vertraut machen.

Für Vorlagen wird auch die Sprache Nix verwendet. Sie können Ihre grundlegenden Funktionen noch einmal auffrischen oder sie als Referenz griffbereit halten.

Struktur der Vorlagendatei

Eine Vorlage ist ein öffentliches GitHub-Repository (oder ein Ordner oder Zweig in einem Repository), das mindestens zwei Dateien enthält:

• 

  Neuen Arbeitsbereich aus einer benutzerdefinierten Vorlage erstellen

  idx-template.json enthält die Metadaten für die Vorlage, einschließlich des für den Nutzer sichtbaren Namen, der Beschreibung und der Parameter, die Nutzern zum Konfigurieren der Vorlage zur Verfügung stehen. Beispielsweise können Sie Ihren Nutzern die Auswahl aus einer Reihe von Programmiersprachen oder Beispielanwendungsfällen ermöglichen. IDX verwendet diese Informationen, um die UI vorzubereiten, die Nutzern angezeigt wird, wenn sie einen neuen Arbeitsbereich aus Ihrer Vorlage erstellen.

• idx-template.nix ist eine Datei, die in der Nix-Sprache geschrieben wurde. Sie enthält ein Bash-Shell-Skript (in einer Nix-Funktion eingebettet), das für Folgendes zuständig ist:

  1. Arbeitsverzeichnis des neuen Arbeitsbereichs erstellen und
  2. Umgebung durch Erstellen einer .idx/dev.nix-Datei einrichten Sie können in diesem Skript auch einfach ein Gerüsttool wie flutter create oder npm init oder ein benutzerdefiniertes Skript ausführen, das in Go, Python, Node.js oder einer anderen Sprache geschrieben ist.

  Diese Datei wird mit den Parametern ausgeführt, die der Nutzer angegeben hat, wenn er die Vorlage konfiguriert.

Neben diesen beiden Dateien können weitere Dateien zur Verwendung in idx-template.nix enthalten sein, um die Vorlage zu instanziieren. Sie können beispielsweise die endgültige .idx/dev.nix-Datei oder sogar alle Scaffolding-Dateien direkt im Repository einbinden.

Einfaches Beispiel: Öffentliches GitHub-Repository in eine Vorlage umwandeln

Bevor wir im Detail darauf eingehen, wie idx-template.json und idx-template.nix definiert werden, ist es hilfreich, sich eine einfache Beispielvorlage anzusehen, die:

• Keine vom Nutzer konfigurierbaren Parameter
• Es werden einfach alle Dateien aus Ihrem Vorlagen-Repository (mit Ausnahme der beiden idx-template-Dateien) in den Arbeitsbereich des Nutzers kopiert. Es sollte bereits ein .idx-Unterordner mit einer dev.nix-Datei vorhanden sein, die die Umgebung definiert.

Wenn Sie die folgenden Dateien zu einem öffentlichen GitHub-Repository (oder Unterordner oder -zweigen) hinzufügen, wird dieses Repository effektiv in eine IDX-Vorlage umgewandelt.

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

Hinweis: Zusätzlich zu $out können Sie die ID des neuen Arbeitsbereichs auch mit $WS_NAME abrufen.

Zusätzliche Systempakete im Skript bootstrap verwenden

Im vorherigen Beispiel werden nur grundlegende POSIX-Befehle verwendet, um Dateien an die richtige Stelle zu kopieren. Für das Skript bootstrap Ihrer Vorlage kann die Installation zusätzlicher Binärdateien erforderlich sein, z. B. git, node oder python3.

Sie können zusätzliche Systempakete für Ihr Bootstrap-Skript verfügbar machen. Dazu geben Sie packages in der Datei idx-template.nix an, genauso wie Sie einen Arbeitsbereich mit zusätzlichen Systempaketen anpassen, indem Sie packages in der Datei dev.nix hinzufügen.

Hinweis: idx-template.nix verwendet immer den Nix-Kanal stable-23.11.

Hier ist ein Beispiel für das Hinzufügen von pkgs.nodejs, das Binärdateien wie node, npx und npm enthält:

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

Wichtig: Das Bootstrap-Skript darf nicht interaktiv sein. Wenn auf eine Nutzereingabe gewartet wird, kann die Vorlage nicht richtig instanziiert werden.

Benutzerdefinierte Parameter hinzufügen

Damit Nutzer den Startpunkt für ihr neues Projekt anpassen können, können Sie entweder mehrere Vorlagen oder eine einzelne Vorlage mit Parametern erstellen. Dies ist eine gute Option, wenn Ihre verschiedenen Ausgangspunkte nur unterschiedliche Werte sind, die an ein CLI-Tool übergeben werden (z. B. --language=js im Vergleich zu --language=ts).

So fügen Sie Parameter hinzu:

1. Beschreiben Sie den Parameter im Objekt params der Metadatendatei idx-template.json. IDX verwendet Informationen in dieser Datei, um die UI vorzubereiten, die Nutzern Ihrer Vorlage angezeigt wird, z. B. Kästchen, Drop-down-Menüs und Textfelder.
2. Aktualisieren Sie das idx-template.nix-Bootstrap, um die Werte zu verwenden, die der Nutzer beim Instanziieren der Vorlage ausgewählt hat.

Beschreiben Sie den Parameter in idx-template.json

Hier ein Beispiel für das Hinzufügen eines enum-Parameters, der in IDX je nach Anzahl der Optionen entweder als Drop-down-Menü oder als Optionsfeldgruppe angezeigt wird:

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

Da es zwei Werte gibt (JavaScript und TypeScript), rendert die UI ein Optionsfeldgruppe für die beiden Optionen und übergibt entweder den Wert ts oder js an das Skript idx-template.nix.

Jedes Parameterobjekt hat die folgenden Eigenschaften:

PROPERTY	SCHREIBMASCHINE	BESCHREIBUNG
id	string	Die eindeutige ID des Parameters, ähnlich einem Variablennamen.
name	string	Der Anzeigename für diesen Parameter.
Typ	string	Gibt die UI-Komponente an, die für diesen Parameter verwendet werden soll, sowie den Datentyp, der an das Bootstrap-Skript übergeben werden soll. Gültige Werte sind: "enum": zeigt eine Drop-down- oder Optionsfeldgruppe an und übergibt ein string an den Bootstrap. "boolean" – zeigt ein Kästchen an und übergibt true oder false "text" – zeigt ein Textfeld an und übergibt ein string-Element
Optionen	object	Bei enum-Parametern stellt dies die Optionen dar, die Nutzern angezeigt werden. Wenn die Option beispielsweise {"js": "JavaScript", ...} lautet, wird „JavaScript“ als Option angezeigt. Wenn diese Option ausgewählt ist, lautet der Wert dieses Parameters js.
default	string oder boolean	Legt den Anfangswert in der Benutzeroberfläche fest. Für enum-Parameter muss dies einer der Schlüssel in options sein. Für boolean-Parameter sollte dies entweder true oder false sein.
erforderlich	boolean	Gibt an, dass dieser Parameter erforderlich ist.

Parameterwerte in idx-template.nix verwenden

Nachdem Sie das Objekt params in der Datei idx-template.json definiert haben, können Sie das Bootstrap-Skript auf Grundlage der vom Nutzer ausgewählten Parameterwerte anpassen.

Wenn Sie dem Beispiel im vorherigen Abschnitt folgen und einen einzelnen Parameter mit der ID language haben, der eine Aufzählung mit den möglichen Werten ts oder js ist, können Sie ihn so verwenden:

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

Ein weiteres gängiges Muster besteht darin, Inhalte abhängig vom Wert eines Strings bedingt einzuschließen. Das vorherige Beispiel könnte auch so geschrieben werden:

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

Wichtig: Erstellen Sie immer eine .idx/dev.nix-Datei im Verzeichnis $out als Teil Ihres bootstrap-Skripts. Wenn die generierte Arbeitsbereichsumgebung je nach vom Nutzer konfigurierten Parametern (z.B. unterschiedliche Systempakete oder Anpassen des onCreate-Hooks) variieren muss, können Sie die Stringbearbeitung in Nix verwenden oder eine Vorlagen-Engine wie jinja2 aufrufen.

Auswählen, welche Dateien standardmäßig geöffnet werden sollen

Sie können festlegen, welche Dateien zum Bearbeiten geöffnet werden sollen, wenn neue Arbeitsbereiche mit Ihrer Vorlage erstellt werden. Wenn Ihre Vorlage beispielsweise für eine einfache Website vorgesehen ist, sollten Sie die Haupt-HTML-, JavaScript- und CSS-Dateien öffnen.

Wenn Sie anpassen möchten, welche Dateien standardmäßig geöffnet werden sollen, aktualisieren Sie Ihre .idx/dev.nix-Datei (nicht Ihre idx-template.nix-Datei!), um einen onCreate-Arbeitsbereich-Hook mit einem openFiles-Attribut hinzuzufügen. Beispiel:

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

Neuen Arbeitsbereich aus Vorlage erstellen

Die einfachste Möglichkeit, eine End-to-End-Testvorlage durchzuführen, ist die Erstellung eines neuen Arbeitsbereichs. Rufen Sie den folgenden Link auf und ersetzen Sie das Beispiel durch die GitHub-Repository-URL Ihrer Vorlage:

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

Optional können Sie einen Zweig und einen Unterordner hinzufügen. Folgendes ist gültig, solange sie öffentlich zugänglich sind:

• 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

Dies ist auch die URL, die Sie mit anderen teilen, damit diese Ihre neue Vorlage verwenden können, oder die URL, auf die Sie über die Schaltfläche In IDX öffnen verlinken.

---

Vorlage teilen

Wenn Sie sich vergewissert haben, dass sich Ihre Vorlage wie erwartet verhält, veröffentlichen Sie sie in einem GitHub-Repository und teilen Sie den Link, den Sie beim Erstellen eines Arbeitsbereichs zum Testen verwendet haben.

Damit Nutzer Ihre Vorlage noch einfacher finden können, fügen Sie der README-Datei Ihrer Website oder Ihres Repositorys die Schaltfläche In IDX öffnen hinzu.