Benutzerdefinierte Vorlage erstellen

Firebase Studio bietet eine breite Palette an integrierten Vorlagen, die alle Dateien, System pakete (z. B. Compiler) und Erweiterungen enthalten, die Sie für einen schnellen Einstieg in eine Sprache oder ein Framework benötigen.

Sie können auch einen Firebase Studio Arbeitsbereich mit Community Vorlagen starten, die auf GitHub gehostet werden. Weitere Informationen zum Starten eines neuen Arbeitsbereichs aus einer Vorlage finden Sie unter Erstellen eines Firebase Studio Arbeitsbereichs.

Die meisten Nutzer verwenden die integrierten Vorlagen oder importieren Projekte aus Git. Für komplexere Anwendungsfälle können Sie jedoch eigene Vorlagen erstellen:

• Wenn Sie ein eigenes Framework, eine eigene Bibliothek oder einen eigenen Dienst erstellen, können Sie Ihren Nutzern einen schnellen Einstieg in Ihre Technologie ermöglichen, ohne den Browser zu verlassen. Dabei steht ihnen die volle Leistung einer cloudbasierten virtuellen Maschine zur Verfügung.

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

• Wenn Sie andere unterrichten, z. B. mit einem Codelab oder einer Anleitung, können Sie einige der ersten Schritte für Ihre Schüler überspringen, indem Sie den Ausgangspunkt für Ihr Codelab als benutzerdefinierte Vorlage vorkonfigurieren.

Nachdem Sie Ihre benutzerdefinierte Vorlage erstellt und getestet haben, können Sie einen Link dafür erstellen und ihn auf Ihrer Website, in der `README`-Datei Ihres Git Repositorys README oder auf der Seite mit den Paketdetails (z. B. in NPM) oder an einer anderen Stelle platzieren, an der Ihre Nutzer Ihre Technologie verwenden sollen.

Tipp: Sie können auch einen Link erstellen, über den Nutzer einen neuen Arbeitsbereich erstellen können, indem sie ein Git-Repository klonen. Diese Methode ist weniger konfigurierbar als das Erstellen einer eigenen Firebase Studio Vorlage, erfordert aber keine Änderungen am Git-Repository. Weitere Informationen finden Sie unter Arbeitsbereich erstellen.

Vorbereitung

Hinweise:

• Informationen zum Anpassen Ihrer Umgebung mit der Datei idx/dev.nix .

• Grundlagen der Nix-Sprache und Referenz

Struktur der Vorlagendatei

Eine Firebase Studio Vorlage ist ein öffentliches Git-Repository (oder ein Ordner oder Branch in einem Repository), das mindestens zwei Dateien enthält:

• idx-template.json enthält die Metadaten für die Vorlage, einschließlich des für Nutzer sichtbaren Namens, der Beschreibung und der Parameter, mit denen Nutzer die Vorlage konfigurieren können. Sie können beispielsweise zulassen, dass Nutzer aus einer Reihe von Programmiersprachen oder Anwendungsfällen auswählen. Firebase Studio verwendet diese Informationen, um die Benutzeroberfläche 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 und ein Bash-Shell Skript enthält, das in eine Nix-Funktion eingebunden ist. Dieses Skript führt folgende Aktionen aus:

  1. Erstellt das Arbeitsverzeichnis für den neuen Arbeitsbereich.

  2. Richtet die Umgebung ein, indem es eine .idx/dev.nix-Datei erstellt. Beachten Sie, dass Sie in diesem Skript auch einfach ein Tool zum Erstellen von Projektgerüsten wie flutter create oder npm init ausführen oder ein benutzerdefiniertes Skript ausführen können, das in Go, Python, Node.js oder einer anderen Sprache geschrieben wurde.

     Diese Datei wird mit den Parametern ausgeführt, die der Nutzer angegeben hat , wenn Firebase Studio die Vorlage lädt.

Neben diesen beiden Dateien können weitere Dateien verwendet werden, die in idx-template.nix verwendet werden, um die Vorlage zu instanziieren. Sie können beispielsweise die endgültige .idx/dev.nix-Datei oder sogar alle Gerüstdateien direkt in das Repository einfügen.

Startervorlage erstellen

Um die Vorlagenerstellung zu beschleunigen, empfehlen wir, mit einer der folgenden Methoden eine Firebase Studio Vorlage zu erstellen, die Sie weiter anpassen können:

• Öffentliches GitHub-Repository in eine Vorlage umwandeln
• Offizielle Vorlage oder Community-Vorlage als Grundlage für Ihre Vorlage verwenden

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

Bevor wir uns mit den Details zum Definieren von idx-template.json und idx-template.nix befassen, sehen wir uns eine einfache Beispielvorlage an, die folgende Merkmale aufweist:

• Enthält keine vom Nutzer konfigurierbaren Parameter.
• Kopiert alle Dateien in Ihrem Vorlagen-Repository (außer den beiden idx-template-Dateien) in den Arbeitsbereich des Nutzers. 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 Branch) hinzufügen, wird dieses Repository effektiv in eine Firebase Studio 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/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}
  '';
}

Hinweis: Neben $out können Sie die neue Arbeitsbereichs-ID auch mit der Variablen $WS_NAME abrufen.

Unter Vorlage anpassen erfahren Sie mehr über zusätzliche Änderungen, die Sie an Ihrer Vorlage vornehmen können.

Benutzerdefinierte Vorlage mit einer offiziellen Vorlage oder Community-Vorlage erstellen

Das Firebase Studio Team verwaltet zwei Repositorys für Firebase Studio Vorlagen:

• Offizielle Vorlagen: Das sind die Vorlagen, die Sie direkt im Firebase Studio Dashboard auswählen, wenn Sie eine neue App erstellen.

• Community-Vorlagen: Diese Vorlagen ermöglichen Beiträge aus der Open-Source-Community. Wenn Sie eine Community-Vorlage verwenden möchten, klonen Sie das Git-Repository für Community-Vorlagen. Sie können den vollständigen Link zur gewünschten Vorlage verwenden.

  Tipp: Wenn Sie einen Beitrag zur Community leisten möchten, indem Sie neue Vorlagen hinzufügen oder vorhandene Vorlagen aktualisieren, senden Sie eine Pull-Anfrage.

So erstellen Sie eine benutzerdefinierte Vorlage auf Basis einer vorhandenen Vorlage:

1. Entscheiden Sie, welche Vorlage Sie als Grundlage für Ihre benutzerdefinierte Vorlage verwenden möchten, und klonen Sie dann das Projekt.

2. Passen Sie idx-template.json, idx-template.nix und .idx/dev.nix nach Bedarf an. Beginnen Sie mit Vorlage anpassen.

3. Checken Sie die Änderungen in Ihr Repository ein.

4. Folgen Sie der Anleitung unter Neuen Arbeitsbereich für Ihre Vorlage erstellen, um Ihre Vorlage zu veröffentlichen und zu testen. Wenn Sie ein verschachteltes Repository verwenden, verlinken Sie direkt darauf in Ihrer URL. Wenn Sie beispielsweise die Community-Vorlage „Vanilla Vite“ verwenden, würden Sie einen neuen Arbeitsbereich mit der folgenden URL bereitstellen und testen:

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

Unter Vorlage anpassen erfahren Sie mehr über zusätzliche Änderungen, die Sie an Ihrer Vorlage vornehmen können.

Vorlage anpassen

Nachdem Sie eine einfache Vorlage erstellt haben, auf der Sie aufbauen können, können Sie die Dateien idx-template.json, idx-template.nix und .idx/dev.nix an Ihre Anforderungen anpassen. Möglicherweise möchten Sie zusätzliche Konfigurationen anpassen:

• Systempakete zu Ihrem bootstrap Skript hinzufügen.
• Vom Nutzer konfigurierbare Parameter hinzufügen
• Auswählen, welche Dateien standardmäßig geöffnet werden sollen
• Standardarbeitsbereichssymbol auswählen

Zusätzliche Systempakete in Ihrem bootstrap-Skript verwenden

Im einfachen Beispiel werden nur grundlegende POSIX-Befehle verwendet, um Dateien an die richtige Stelle zu kopieren. Für das bootstrap-Skript Ihrer Vorlage müssen möglicherweise zusätzliche Binärdateien installiert werden, z. B. git, node, python3 oder andere.

Sie können zusätzliche Systempakete für Ihr Bootstrap-Skript verfügbar machen, indem Sie packages in Ihrer idx-template.nix Datei angeben. So würden Sie auch einen Arbeitsbereich mit zusätzlichen Systempaketen anpassen, indem Sie packages in der dev.nix Datei hinzufügen.

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

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: Ihr Bootstrap-Skript darf nicht interaktiv sein. Wenn es auf eine Nutzereingabe wartet, kann die Vorlage nicht richtig instanziiert werden.

Vom Nutzer konfigurierbare Parameter hinzufügen

Wenn Sie Nutzern die Möglichkeit geben möchten, den Ausgangspunkt für ihr neues Projekt anzupassen, können Sie entweder mehrere Vorlagen oder eine einzelne Vorlage mit Parametern erstellen. Dies ist eine gute Option, wenn sich Ihre verschiedenen Ausgangspunkte nur durch unterschiedliche Werte unterscheiden, 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 Ihrer Metadatendatei idx-template.json. Firebase Studio verwendet die Informationen in dieser Datei, um die Benutzeroberfläche (z. B. Kästchen, Drop-down-Menüs und Textfelder) vorzubereiten, die Nutzern Ihrer Vorlage angezeigt wird.
2. Aktualisieren Sie Ihr idx-template.nix-Bootstrap-Skript, um die Werte zu verwenden, die der Nutzer beim Instanziieren der Vorlage ausgewählt hat.

Parameter in idx-template.json beschreiben

Hier ist ein Beispiel für das Hinzufügen eines enum Parameters, der Firebase Studio 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), wird in der Benutzeroberfläche eine Optionsfeldgruppe für die beiden Optionen gerendert und entweder der Wert ts oder js an das idx-template.nix-Skript übergeben.

Jedes Parameterobjekt hat die folgenden Attribute:

PROPERTY	TYP	BESCHREIBUNG
id	string	Die eindeutige ID des Parameters, ähnlich einem Variablennamen.
name	string	Der Anzeigename für diesen Parameter.
type	string	Gibt die UI-Komponente an, die für diesen Parameter verwendet werden soll, und den Datentyp, der an das Bootstrap-Skript übergeben werden soll. Gültige Werte sind: "enum" – Zeigt ein Drop-down-Menü oder eine Optionsfeldgruppe an und übergibt ein string an das Bootstrap-Skript. "boolean": Zeigt ein Kästchen an und übergibt true oder false. "text" – Zeigt ein Textfeld an und übergibt einen string
options	object	Für enum-Parameter sind dies die Optionen, die Nutzern angezeigt werden. Wenn die Optionen beispielsweise {"js": "JavaScript", ...} sind, wird „JavaScript“ als Option angezeigt. Wenn diese Option ausgewählt wird, ist 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 muss dies entweder true oder false sein.
required	boolean	Gibt an, dass dieser Parameter erforderlich ist.

Parameterwerte in idx-template.nix verwenden

Nachdem Sie das Objekt params in Ihrer idx-template.json-Datei definiert haben, können Sie das Bootstrap-Skript basierend auf den Parameterwerten anpassen, die der Nutzer auswählt.

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 bedingt einzufügen, je nach Wert eines Strings. Das vorherige Beispiel kann auch so geschrieben werden:

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

Wichtig: Achten Sie darauf, dass Ihr bootstrap Skript immer eine .idx/dev.nix Datei im $out Verzeichnis erstellt. Wenn die generierte Arbeitsbereichs umgebung je nach den vom Nutzer konfigurierten Parametern variieren muss (z. B. durch Einbeziehen verschiedener Systempakete oder Anpassen des onCreate Hooks), können Sie Stringmanipulationen in Nix verwenden oder eine Vorlagen-Engine wie jinja2 aufrufen.

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

Es empfiehlt sich, anzupassen, 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 ist, möchten Sie möglicherweise die wichtigsten 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) so, dass sie einen onCreate-Arbeitsbereichs-Hook mit einem openFiles-Attribut enthält:

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

Standardarbeitsbereichssymbol auswählen

Sie können das Standardsymbol für Arbeitsbereiche auswählen, die mit Ihrer Vorlage erstellt wurden, indem Sie eine PNG-Datei mit dem Namen icon.png neben der Datei dev.nix im Verzeichnis .idx platzieren.

Hinweis: Die Datei idx-template.json enthält auch die optionale Property icon, die, falls angegeben, auf eine öffentliche PNG- oder SVG-URL verweisen sollte. Dieses Feld wird in Firebase Studionicht verwendet.

Vorlage in einem neuen Arbeitsbereich testen

Die einfachste Möglichkeit, Ihre Vorlage umfassend zu testen, besteht darin, einen neuen Arbeitsbereich damit zu erstellen. 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 Branch und einen Unterordner angeben. Alle folgenden URLs sind gültig, sofern 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 für andere freigeben, damit sie Ihre neue Vorlage verwenden können, oder die URL, auf die Sie über die Schaltfläche „In Firebase Studio öffnen“ verlinken.

---

Vorlage freigeben

Nachdem Sie bestätigt haben, dass sich Ihre Vorlage wie erwartet verhält, veröffentlichen Sie sie in einem GitHub-Repository und geben Sie denselben Link frei, den Sie beim Erstellen eines Arbeitsbereichs zum Testen verwendet haben.

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