Tworzenie szablonu niestandardowego

Firebase Studio udostępnia szeroki zakres wbudowanych szablonów, które zawierają wszystkie pliki, pakiety systemowe (np. kompilatory) i rozszerzenia, których potrzebujesz, aby szybko rozpocząć pracę z językiem lub frameworkiem.

Możesz też uruchomić środowisko Firebase Studio, korzystając z szablonów społeczności hostowanych na GitHubie. Więcej informacji o uruchamianiu nowej sekcji Workspace na podstawie szablonu znajdziesz w artykule Tworzenie sekcji Firebase StudioWorkspace.

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

• Jeśli tworzysz własny framework, bibliotekę lub usługę, możesz pozwolić użytkownikom na szybkie rozpoczęcie korzystania z Twojej technologii bez wychodzenia z przeglądarki, korzystając z pełnej mocy maszyny wirtualnej w chmurze.

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

• Jeśli uczysz innych, np. za pomocą samouczka lub laboratorium programistycznego, możesz usunąć niektóre początkowe kroki dla uczniów, wstępnie konfigurując punkt początkowy laboratorium programistycznego jako szablon niestandardowy.

Po utworzeniu i przetestowaniu szablonu niestandardowego możesz utworzyć link do niego, który umieścisz w swojej witrynie, pliku README repozytorium Git, stronie z informacjami o pakiecie (np. w NPM) lub innym miejscu, w którym użytkownicy mają zacząć korzystać z Twojej technologii.

Wymagania wstępne

Zanim zaczniesz:

• Dowiedz się, jak za pomocą pliku idx/dev.nix dostosowywać środowisko.

• Zapoznaj się z podstawami języka Nix i miej pod ręką materiały referencyjne.

Struktura pliku szablonu

Szablon Firebase Studio 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żytkowników, opis i parametry dostępne dla użytkowników do konfigurowania szablonu. Możesz na przykład zezwolić użytkownikom na wybór spośród kilku języków programowania lub podać przykładowe przypadki użycia. Firebase Studio używa tych informacji do przygotowania interfejsu użytkownika wyświetlanego 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 (opakowany w funkcję Nix), który:

  1. Tworzy katalog roboczy dla nowego obszaru roboczego.

  2. Skonfiguruj środowisko, tworząc plik .idx/dev.nix. Pamiętaj, że w tym skrypcie możesz też uruchomić narzędzie do tworzenia szablonu projektu, takie jak 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 dwóch plików można dołączyć inne pliki, które będą używane w pliku idx-template.nix do tworzenia instancji szablonu. Możesz na przykład dołączyć plik .idx/dev.nix z ostateczną wersją lub nawet wszystkie pliki szablonu bezpośrednio w repozytorium.

Tworzenie szablonu podstawowego

Aby przyspieszyć tworzenie szablonów, zalecamy użycie jednej z tych metod:Firebase Studio

• Konwertowanie dowolnego publicznego repozytorium GitHub na szablon
• Użyj oficjalnego szablonu lub szablonu z galerii jako podstawy dla swojego szablonu

Przykład podstawowy: przekształcenie dowolnego publicznego repozytorium GitHub w szablon

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

• Nie zawiera parametrów, które można konfigurować.
• kopiuje wszystkie pliki z repozytorium szablonów (z wyjątkiem 2 plików idx-template) do obszaru roboczego użytkownika. Powinien już istnieć podfolder .idx z pliku dev.nix definiującym środowisko.

Jeśli dodasz te pliki do publicznego repozytorium GitHub (lub podfolderu lub gałęzi), repozytorium stanie się szablonem Firebase Studio.

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 szablonie, przejdź do sekcji Dostosowywanie szablonu.

Tworzenie szablonu niestandardowego na podstawie szablonu oficjalnego lub udostępnionego przez społeczność

Zespół Firebase Studio zarządza 2 repozytoriami szablonów Firebase Studio:

• Oficjalne szablony: to szablony, które wybierasz bezpośrednio na Firebase Studiopanelu sterowania podczas tworzenia nowej aplikacji.

• Szablony społeczności: te szablony umożliwiają tworzenie treści przez społeczność zajmującą się oprogramowaniem typu open source. Aby użyć szablonu utworzonego przez członka społeczności, sklonuj repozytorium Git szablonów społeczności. Możesz użyć pełnego linku do szablonu, którego chcesz użyć.

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

1. Zdecyduj, którego szablonu użyjesz jako podstawy do szablonu niestandardowego, a następnie sklonuj projekt.

2. W razie potrzeby dostosuj pola idx-template.json, idx-template.nix i .idx/dev.nix, zaczynając od sekcji Dostosowywanie szablonu.

3. Sprawdź zmiany w repozytorium.

4. Aby opublikować i przetestować szablon, wykonaj czynności opisane w sekcji Tworzenie nowego workspace dla szablonu. Jeśli używasz repozytorium zagnieżdżonego, umieść w adresie URL bezpośredni link do niego. Jeśli na przykład używasz szablonu „Vanilla Vite” udostępnionego przez społeczność, możesz skonfigurować i przetestować nową przestrzeń roboczą, korzystając z tego adresu URL:

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

Aby dowiedzieć się więcej o dodatkowych zmianach, które możesz wprowadzić w szablonie, 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:

• Dodaj pakiety systemowe do skryptu bootstrap.
• Dodawanie parametrów konfigurowalnych przez użytkownika
• Wybieranie plików, które mają otwierać się domyślnie
• Wybieranie ikony domyślnego obszaru roboczego

Używanie dodatkowych pakietów systemowych w skrypcie bootstrap

Podstawowy przykład zawiera tylko podstawowe polecenia POSIX służące do kopiowania plików we właściwe miejsce. Skrypt bootstrap w tym szablonie może wymagać zainstalowania dodatkowych plików binarnych, takich jak git, node, python3 lub innych.

Aby udostępnić dodatkowe pakiety systemowe skryptowi bootstrap, w pliku idx-template.nix określ packages, tak jak dostosowujesz obszar roboczy za pomocą dodatkowych pakietów systemowych, dodając do pliku packages w pliku dev.nix.

Oto przykład dodawania pakietu 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 konfigurowalnych przez użytkownika

Aby umożliwić użytkownikom dostosowanie punktu początkowego nowego projektu, możesz utworzyć kilka szablonów lub jeden szablon z parametrami. Jest to świetna opcja, jeśli różne punkty początkowe to po prostu różne wartości przekazywane do narzędzia wiersza poleceń (np. --language=js w porównaniu z --language=ts).

Aby dodać parametry:

1. Opisz parametr w obiekcie params w pliku metadanych idx-template.json. Firebase Studio korzysta z informacji w tym pliku, aby przygotować interfejs użytkownika (np. pola wyboru, listy rozwijane i pola tekstowe) wyświetlane użytkownikom szablonu.
2. Zaktualizuj bootstrap idx-template.nix, aby używać wartości wybranych przez użytkownika podczas tworzenia wystąpienia szablonu.

Opisz parametr idx-template.json

Oto przykład dodawania parametru enum, który Firebase Studio wyświetla się jako menu lub grupa przycisków opcji 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:

Używanie wartości parametrów w pliku 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 w poprzedniej sekcji, jeśli masz 1 parametr o identyfikatorze language, który jest typem enumeracji o możliwych wartościach 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 typowym wzorcem jest warunkowe uwzględnianie treści w zależności od wartości ciągu znaków. Poprzedni przykład można też zapisać w ten sposób:

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

Wybieranie plików, które mają otwierać się domyślnie

Warto określić, które pliki mają być otwierane do edycji podczas tworzenia nowych przestrzeni roboczych za pomocą szablonu. Jeśli na przykład szablon dotyczy podstawowej witryny, możesz otworzyć główne pliki HTML, JavaScript i CSS.

Aby określić, które pliki mają się otwierać domyślnie, zaktualizuj plik .idx/dev.nix (nie plik idx-template.nix), aby zawierał element onCreate 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

Domyślną ikonę dla Workspace utworzonych za pomocą szablonu możesz wybrać, umieszczając obok pliku dev.nix w katalogu .idx plik PNG o nazwie icon.png.

Testowanie szablonu w nowym obszarze roboczym

Najprostszym sposobem kompleksowego przetestowania szablonu jest utworzenie 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 podać gałąź i podfolder. Wszystkie te elementy są ważne, 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

To też adres URL, który udostępnisz innym, aby mogli korzystać z Twojego nowego szablonu. Możesz też użyć go w przycisku „Otwórz w Firebase Studio”.

Udostępnianie szablonu

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

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