Tworzenie szablonu niestandardowego

Firebase Studio oferuje szeroki wybór wbudowanych szablonów, które zawierają wszystkie pliki, pakiety systemowe (np. kompilatory) i rozszerzenia potrzebne do szybkiego rozpoczęcia pracy z językiem lub platformą.

Możesz też uruchomić przestrzeń roboczą Firebase Studio, korzystając z szablonów Community hostowanych na GitHubie. Więcej informacji o uruchamianiu nowej przestrzeni roboczej na podstawie szablonu znajdziesz w artykule Tworzenie przestrzeni roboczej.Firebase Studio

Większość użytkowników będzie korzystać z wbudowanych szablonów lub importować projekty z Gita, ale w bardziej zaawansowanych przypadkach możesz tworzyć własne szablony:

  • Jeśli tworzysz własne środowisko, bibliotekę lub usługę, możesz umożliwić użytkownikom szybkie rozpoczęcie korzystania z Twojej technologii bez opuszczania przeglądarki, z pełną mocą wirtualnej maszyny w chmurze.

  • Jeśli masz preferowany stos technologii do projektów, możesz uprościć proces rozpoczynania nowych projektów za pomocą szablonu niestandardowego.

  • Jeśli prowadzisz szkolenie, np. w formie samouczka lub warsztatów programistycznych, możesz pominąć niektóre początkowe kroki dla uczestników, wstępnie konfigurując punkt początkowy warsztatów programistycznych jako niestandardowy szablon.

Po utworzeniu i przetestowaniu niestandardowego szablonu możesz utworzyć do niego link, aby umieścić go w witrynie, w repozytorium Git, w pliku README, na stronie szczegółów pakietu (np. w NPM) lub w dowolnym innym miejscu, w którym użytkownicy mogą zacząć korzystać z Twojej technologii.

Wymagania wstępne

Zanim zaczniesz:

Struktura pliku szablonu

Firebase Studio Szablon to publiczne repozytorium Git (lub folder lub gałąź w repozytorium), które zawiera co najmniej 2 pliki:

  • idx-template.json zawiera metadane szablonu, w tym jego nazwę widoczną dla użytkownika, opis i parametry dostępne dla użytkowników do konfigurowania szablonu. Możesz na przykład umożliwić użytkownikom wybór spośród wielu języków programowania lub przykładowych przypadków użycia. Firebase Studio wykorzystuje te informacje do przygotowania interfejsu, który jest wyświetlany użytkownikom, gdy zdecydują się utworzyć nowy obszar roboczy na podstawie Twojego szablonu.

  • idx-template.nix to plik napisany w języku Nix, który zawiera skrypt powłoki Bash (zawarty w funkcji Nix), który:

    1. Tworzy katalog roboczy dla nowego obszaru roboczego.

    2. konfiguruje środowisko, tworząc plik .idx/dev.nix, Pamiętaj, że w tym skrypcie możesz też uruchomić narzędzie do tworzenia szkieletu projektu, np. flutter create lub npm init, albo uruchomić skrypt niestandardowy napisany w języku Go, Python, Node.js lub innym.

      Ten plik zostanie wykonany z parametrami określonymi przez użytkownika, gdy Firebase Studio wczyta szablon.

Oprócz tych 2 plików można dołączyć inne pliki, które będą używane w idx-template.nix do utworzenia instancji szablonu. Możesz na przykład dodać końcowy plik .idx/dev.nix lub nawet wszystkie pliki szkieletowe bezpośrednio w repozytorium.

Tworzenie szablonu początkowego

Aby przyspieszyć tworzenie szablonu, zalecamy rozpoczęcie od jednej z tych metod utworzenia szablonu Firebase Studio, który możesz dalej dostosowywać:

Podstawowy przykład: przekształcanie dowolnego publicznego repozytorium GitHub w szablon

Zanim przejdziemy do szczegółów definiowania idx-template.json i idx-template.nix, warto zapoznać się z podstawowym szablonem, który:

  • Nie zawiera parametrów konfigurowanych przez użytkownika.
  • Kopiuje wszystkie pliki z repozytorium szablonu (z wyjątkiem 2 plików idx-template) do obszaru roboczego użytkownika. Powinien już istnieć podfolder .idx z plikiem dev.nix, który definiuje środowisko.

Jeśli dodasz te pliki do dowolnego publicznego repozytorium GitHub (lub podfolderu lub gałęzi), przekształcisz to repozytorium w Firebase Studio szablon.

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

Aby dowiedzieć się więcej o dodatkowych zmianach, które możesz wprowadzić w celu dostosowania szablonu, przejdź do sekcji Dostosowywanie szablonu.

Tworzenie szablonu niestandardowego na podstawie oficjalnego szablonu lub szablonu społeczności

Zespół Firebase Studio prowadzi 2 repozytoria szablonów:Firebase Studio

Aby utworzyć szablon niestandardowy na podstawie istniejącego szablonu:

  1. Wybierz szablon, który będzie podstawą Twojego szablonu niestandardowego, a następnie sklonuj projekt.

  2. W razie potrzeby dostosuj idx-template.json, idx-template.nix i .idx/dev.nix, zaczynając od Dostosuj szablon.

  3. Zatwierdź zmiany w repozytorium.

  4. Aby opublikować i przetestować szablon, postępuj zgodnie z instrukcjami w artykule Tworzenie nowego obszaru roboczego dla szablonu. Jeśli używasz zagnieżdżonego repozytorium, w adresie URL podaj do niego bezpośredni link. Jeśli na przykład używasz szablonu społeczności „Vanilla Vite”, możesz utworzyć i przetestować nowy obszar roboczy, korzystając z tego adresu URL:

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

Aby dowiedzieć się więcej o dodatkowych zmianach, które możesz wprowadzić w celu dostosowania szablonu, przejdź do sekcji Dostosowywanie szablonu.

Dostosowywanie szablonu

Po utworzeniu podstawowego szablonu możesz edytować pliki idx-template.json, idx-template.nix i .idx/dev.nix, aby dostosować je do swoich wymagań. Możesz dostosować dodatkowe konfiguracje:

Używanie dodatkowych pakietów systemowych w skrypcie bootstrap

W podstawowym przykładzie używane są tylko podstawowe polecenia POSIX do kopiowania plików we właściwe miejsce. Skrypt bootstrap w Twoim szablonie może wymagać zainstalowania dodatkowych plików binarnych, takich jak git, node, python3 lub inne.

Możesz udostępnić dodatkowe pakiety systemowe skryptowi początkowemu, określając packages w pliku idx-template.nix, tak jak dostosowujesz obszar roboczy za pomocą dodatkowych pakietów systemowych, dodając je do packages w pliku dev.nix.

Oto przykład dodawania elementu pkgs.nodejs, który zawiera pliki binarne, takie jak node, npx i 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"
  ''
}

Dodawanie parametrów konfigurowanych przez użytkownika

Aby umożliwić użytkownikom dostosowywanie punktu początkowego nowego projektu, możesz utworzyć wiele szablonów lub jeden szablon z parametrami. Jest to świetne rozwiązanie, jeśli różne punkty początkowe to tylko różne wartości przekazywane do narzędzia CLI (np. --language=js i --language=ts).

Aby dodać parametry:

  1. Opisz parametr w obiekcie params pliku metadanychidx-template.json. Firebase Studio wykorzystuje informacje z tego pliku do przygotowania interfejsu (np. pól wyboru, menu i pól tekstowych) wyświetlanego użytkownikom szablonu.
  2. Zaktualizuj idx-template.nix bootstrap, aby używać wartości wybranych przez użytkownika podczas tworzenia instancji szablonu.

Opisz parametr w idx-template.json

Oto przykład dodawania parametru enum, który Firebase Studio wyświetla się jako menu lub grupa przycisków, w zależności od liczby opcji:

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

Ponieważ są 2 wartości (JavaScript i TypeScript), interfejs wyświetli grupę przycisków opcji dla tych 2 opcji i przekaże wartość ts lub js do skryptu idx-template.nix.

Każdy obiekt parametru ma te właściwości:

USŁUGA TYP OPIS
id string Unikalny identyfikator parametru, podobny do nazwy zmiennej.
nazwa string Wyświetlana nazwa tego parametru.
typ string

Określa komponent interfejsu, który ma być używany w przypadku tego parametru, oraz typ danych, który ma być przekazywany do skryptu bootstrap. Prawidłowe wartości:

  • "enum" – wyświetla menu lub grupę opcji i przekazuje wartość string do bootstrapa.
  • "boolean" – wyświetla pole wyboru i przekazuje wartość true lub false.
  • "text" – wyświetla pole tekstowe i przekazuje string
opcje object W przypadku parametrów enum są to opcje wyświetlane użytkownikom. Jeśli na przykład opcje to {"js": "JavaScript", ...}, opcja „JavaScript” będzie wyświetlana jako opcja, a po jej wybraniu wartością tego parametru będzie js.
domyślna string lub boolean Ustawia wartość początkową w interfejsie. W przypadku parametrów enum musi to być jeden z kluczy w options. W przypadku parametrów boolean powinna to być wartość true lub false.
wymagane boolean Oznacza, że ten parametr jest wymagany.

Używanie wartości parametrów w idx-template.nix

Po zdefiniowaniu obiektu params w pliku idx-template.json możesz zacząć dostosowywać skrypt bootstrap na podstawie wartości parametrów wybranych przez użytkownika.

Zgodnie z przykładem z poprzedniej sekcji, jeśli masz jeden parametr o identyfikatorze language, który jest wyliczeniem z możliwymi wartościami ts lub js, możesz go użyć w ten sposób:

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

Innym częstym wzorcem jest warunkowe uwzględnianie treści w zależności od wartości ciągu znaków. Inny sposób na zapisanie poprzedniego przykładu:

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

Wybieranie plików, które mają być otwierane domyślnie

Warto dostosować, które pliki mają być otwierane do edycji, gdy nowe obszary robocze są tworzone na podstawie Twojego szablonu. Jeśli na przykład szablon jest przeznaczony dla podstawowej witryny, możesz otworzyć główne pliki HTML, JavaScript i CSS.

Aby dostosować, które pliki mają się domyślnie otwierać, zaktualizuj plik .idx/dev.nix (nie plik idx-template.nix!), aby zawierał onCreate element zaczepienia obszaru roboczego z atrybutem openFiles, na przykład:

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

Wybieranie domyślnej ikony obszaru roboczego

Możesz wybrać domyślną ikonę dla obszarów roboczych utworzonych na podstawie Twojego szablonu, umieszczając plik PNG o nazwie icon.png obok pliku dev.nix w katalogu .idx.

Testowanie szablonu w nowym obszarze roboczym

Najprostszym sposobem kompleksowego przetestowania szablonu jest utworzenie z jego pomocą nowego obszaru roboczego. Otwórz ten link, zastępując przykład adresem URL repozytorium GitHub szablonu:

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

Opcjonalnie możesz dodać gałąź i podfolder. Wszystkie poniższe adresy są prawidłowe, o ile są publicznie dostępne:

  • 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

Jest to też adres URL, który możesz udostępniać innym, aby mogli korzystać z Twojego nowego szablonu, lub adres URL, do którego możesz dodać link z przycisku „Otwórz w Firebase Studio”.

Udostępnianie szablonu

Po potwierdzeniu, że szablon działa zgodnie z oczekiwaniami, opublikuj go w repozytorium GitHub i udostępnij ten sam link, którego używasz podczas tworzenia obszaru roboczego na potrzeby testowania.

Aby jeszcze bardziej ułatwić użytkownikom znalezienie Twojego szablonu, dodaj do pliku README w swojej witrynie lub repozytorium przycisk „Otwórz w Firebase Studio”.