Tworzenie szablonu niestandardowego

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

Możesz też uruchomić obszar roboczy Firebase Studio, korzystając z szablonów społecznościowych hostowanych na GitHubie. Więcej informacji o uruchamianiu nowego obszaru roboczego na podstawie szablonu znajdziesz w artykule Tworzenie obszaru roboczego 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łasny framework, bibliotekę lub usługę, możesz umożliwić użytkownikom szybkie rozpoczęcie pracy z Twoją technologią bez opuszczania przeglądarki, z pełną mocą maszyny wirtualnej w chmurze.

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

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

Po utworzeniu i przetestowaniu szablonu niestandardowego możesz utworzyć do niego link, który umieścisz w witrynie, w repozytorium Git README pliku, 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:

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

• Zapoznaj się z podstawami języka Nix i miej pod ręką dokumentację.

Struktura pliku szablonu

Szablon Firebase Studio to publiczne repozytorium Git (lub folder albo 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, które użytkownicy mogą skonfigurować. Możesz na przykład umożliwić użytkownikom wybór spośród kilku języków programowania lub przykładowych przypadków użycia. Firebase Studio używa tych informacji do przygotowania interfejsu użytkownika wyświetlanego, gdy użytkownicy 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):

  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ż po prostu uruchomić narzędzie do tworzenia szkieletu 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 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 dołączyć końcowy plik .idx/dev.nix lub nawet wszystkie pliki szkieletu 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ć:

• Przekształć dowolne publiczne repozytorium GitHub w szablon.
• Użyj oficjalnego szablonu lub szablonu utworzonego przez członka społeczności jako podstawy szablonu.

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

Zanim przejdziesz do szczegółów definiowania plików idx-template.json i idx-template.nix, warto zapoznać się z podstawowym przykładem szablonu, 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 albo gałęzi), repozytorium to stanie się Firebase Studio szablonem.

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ć, aby dostosować szablon, przejdź do sekcji Dostosowywanie szablonu.

Tworzenie szablonu niestandardowego na podstawie oficjalnego szablonu lub szablonu utworzonego przez członka społeczności

Zespół Firebase Studio utrzymuje 2 repozytoria dla Firebase Studio szablonów:

• Oficjalne szablony: Są to szablony, które wybierasz bezpośrednio z Firebase Studio panelu podczas tworzenia nowej aplikacji.

• Szablony społeczności: Te szablony umożliwiają wnoszenie wkładu przez społeczność 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. Wybierz szablon, którego chcesz użyć jako podstawy szablonu niestandardowego, a następnie sklonuj projekt.

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

3. Zatwierdź zmiany w repozytorium.

4. Aby opublikować i przetestować szablon, postępuj zgodnie z instrukcjami w artykule Tworzenie nowego obszaru roboczego na potrzeby szablonu. Jeśli używasz repozytorium zagnieżdżonego, podaj w adresie URL bezpośredni link do niego. Jeśli na przykład używasz szablonu społeczności „Vanilla Vite”, utworzysz i przetestujesz nowy obszar roboczy za pomocą 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ć, aby dostosować szablon, przejdź do sekcji Dostosowywanie szablonu.

Dostosowywanie szablonu

Teraz, gdy masz już podstawowy szablon, na którym możesz się opierać, możesz edytować pliki idx-template.json, idx-template.nix i .idx/dev.nix, aby dopasować je do swoich wymagań. Możesz dostosować dodatkowe konfiguracje:

• Dodaj pakiety systemowe do skryptu bootstrap.
• Dodaj parametry konfigurowane przez użytkownika.
• Wybierz pliki, które mają być otwierane domyślnie.
• Wybierz domyślną ikonę obszaru roboczego.

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 szablonu może wymagać zainstalowania dodatkowych plików binarnych, takich jak git, node, python3 lub inne.

Możesz udostępnić dodatkowe pakiety systemowe skryptowi bootstrap 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 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 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 tylko różne wartości przekazywane do narzędzia CLI (np. --language=js a --language=ts).

Aby dodać parametry:

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

Opisywanie parametru w pliku idx-template.json

Oto przykład dodawania parametru enum, który Firebase Studio wyświetla jako menu rozwijane lub grupę 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 użytkownika 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.

Jeśli zgodnie z przykładem z poprzedniej sekcji 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 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ą być otwierane domyślnie

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

Aby dostosować, które pliki mają być otwierane domyślnie, zaktualizuj plik .idx/dev.nix (nie plik idx-template.nix!), aby uwzględnić hook obszaru roboczego onCreate z atrybutem openFiles:

# .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ę obszarów roboczych utworzonych za pomocą 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 na przetestowanie szablonu od początku do końca jest utworzenie z jego użyciem 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 adresy URL 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 udostępnisz innym, aby mogli korzystać z Twojego nowego szablonu, lub adres URL, do którego prowadzi przycisk „Otwórz w Firebase Studio” button.

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 obszaru roboczego na potrzeby testowania.

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