Membuat template kustom

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Firebase Studio menawarkan berbagai template bawaan yang mencakup semua file, paket sistem (misalnya, compiler), dan ekstensi yang diperlukan untuk mulai menggunakan bahasa atau framework dengan cepat.

Anda juga dapat meluncurkan ruang kerja Firebase Studio menggunakan template Komunitas yang dihosting di GitHub. Untuk mengetahui informasi selengkapnya tentang cara meluncurkan ruang kerja baru dari template, lihat Membuat ruang kerja Firebase Studio.

Sebagian besar pengguna akan menggunakan template bawaan atau mengimpor project dari Git, tetapi untuk kasus penggunaan lanjutan, Anda dapat membuat template Anda sendiri:

• Jika Anda mem-build framework, library, atau layanan sendiri, Anda dapat memungkinkan pengguna memulai teknologi Anda dengan cepat tanpa harus meninggalkan browser, dengan kemampuan penuh virtual machine berbasis cloud.

• Jika memiliki technology stack pilihan untuk project Anda, Anda dapat menyederhanakan proses untuk memulai project baru dengan template kustom.

• Jika Anda mengajari orang lain, seperti melalui tutorial atau codelab, Anda dapat menghapus beberapa langkah awal untuk siswa dengan mengonfigurasi terlebih dahulu titik awal untuk codelab sebagai template kustom.

Setelah membuat dan menguji template kustom, Anda dapat membuat link untuk codelab tersebut guna ditempatkan di situs, file README repositori Git, halaman detail paket (misalnya, di NPM), atau tempat lain di mana pengguna mungkin mulai menggunakan teknologi Anda.

Prasyarat

Sebelum memulai:

• Pelajari cara menggunakan file idx/dev.nix untuk menyesuaikan lingkungan Anda.

• Pelajari dasar-dasar bahasa Nix dan simpan referensinya di tempat yang mudah ditemukan.

Struktur file template

Template Firebase Studio adalah repositori Git publik (atau folder atau cabang dalam repositori) yang berisi minimal dua file:

• idx-template.json mencakup metadata untuk template, termasuk nama, deskripsi, dan parameter yang terlihat pengguna yang tersedia bagi pengguna untuk mengonfigurasi template. Misalnya, Anda dapat mengizinkan pengguna memilih dari sejumlah bahasa pemrograman, atau contoh kasus penggunaan. Firebase Studio menggunakan informasi ini untuk menyiapkan UI yang ditampilkan kepada pengguna saat mereka memilih untuk membuat ruang kerja baru dari template Anda.

• idx-template.nix adalah file yang ditulis dengan bahasa Nix yang berisi skrip shell Bash (tergabung dalam fungsi Nix) yang:

  1. Membuat direktori kerja untuk ruang kerja baru.

  2. Menyiapkan lingkungannya dengan membuat file .idx/dev.nix. Perhatikan bahwa Anda juga dapat menjalankan alat scaffolding project seperti flutter create atau npm init dalam skrip ini, atau menjalankan skrip kustom yang ditulis dalam Go, Python, Node.js, atau bahasa lain.

     File ini akan dieksekusi dengan parameter yang ditentukan oleh pengguna saat Firebase Studio memuat template.

File lain dapat disertakan bersama kedua file ini, untuk digunakan dalam idx-template.nix, guna membuat instance template. Misalnya, Anda dapat menyertakan file .idx/dev.nix final, atau bahkan menyertakan semua file scaffolding langsung di repositori.

Membuat template awal

Untuk mempercepat pembuatan template, sebaiknya Anda memulai dengan salah satu metode berikut guna membuat template Firebase Studio yang dapat disesuaikan lebih lanjut:

• Mengubah repositori GitHub publik menjadi template
• Menggunakan template resmi atau komunitas sebagai dasar untuk template Anda

Contoh dasar: Mengubah repositori GitHub publik menjadi template

Sebelum membahas lebih detail cara menentukan idx-template.json dan idx-template.nix, sebaiknya lihat template contoh dasar yang:

• Tidak berisi parameter yang dapat dikonfigurasi pengguna.
• Menyalin semua file di repositori template Anda (kecuali dua file idx-template) ke ruang kerja pengguna. Akan sudah tersedia subfolder .idx dengan file dev.nix yang menentukan lingkungan.

Jika Anda menambahkan file berikut ke repositori GitHub publik (atau subfolder atau cabang), tindakan ini akan secara efektif mengubah repositori tersebut menjadi template 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}
  '';
}

Lanjutkan ke Menyesuaikan template guna mempelajari perubahan tambahan yang dapat Anda lakukan untuk menyesuaikan template.

Membuat template kustom menggunakan template resmi atau komunitas

Tim Firebase Studio mengelola dua repositori untuk template Firebase Studio:

• Template resmi: Template ini adalah template yang Anda pilih langsung dari dasbor Firebase Studio saat membuat aplikasi baru.

• Template komunitas: Template ini memungkinkan kontribusi dari komunitas open source. Untuk menggunakan template komunitas, clone repositori Git Template komunitas. Anda dapat menggunakan link lengkap ke template yang ingin digunakan.

Untuk membuat template kustom dengan template yang ada sebagai dasar:

1. Tentukan template yang akan digunakan sebagai dasar untuk template kustom Anda, lalu clone projectnya.

2. Sesuaikan idx-template.json, idx-template.nix, dan .idx/dev.nix sesuai kebutuhan, mulai dengan Menyesuaikan template Anda.

3. Periksa perubahan di repositori Anda.

4. Ikuti cara Membuat ruang kerja baru untuk template Anda guna memublikasikan dan menguji template Anda. Jika Anda menggunakan repositori bertingkat, hubungkan langsung dengan repositori tersebut di URL Anda. Misalnya, jika menggunakan template "Vanilla Vite" komunitas, Anda akan menyediakan dan menguji ruang kerja baru menggunakan URL berikut:

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

Lanjutkan ke Menyesuaikan template guna mempelajari perubahan tambahan yang dapat Anda lakukan untuk menyesuaikan template.

Menyesuaikan template

Setelah membuat template dasar untuk di-build, Anda dapat mengedit file idx-template.json, idx-template.nix, dan .idx/dev.nix agar sesuai dengan persyaratan Anda. Anda mungkin perlu menyesuaikan konfigurasi tambahan berikut:

• Menambahkan paket sistem ke skrip bootstrap.
• Menambahkan parameter yang dapat dikonfigurasi pengguna
• Memilih file yang akan dibuka secara default
• Memilih ikon ruang kerja default

Menggunakan paket sistem tambahan dalam skrip bootstrap

Contoh dasar hanya menggunakan perintah POSIX dasar untuk menyalin file ke tempat yang tepat. Skrip bootstrap template Anda mungkin memerlukan penginstalan program biner tambahan, seperti git, node, python3, atau lainnya.

Anda dapat menyediakan paket sistem tambahan ke skrip bootstrap dengan menentukan packages dalam file idx-template.nix, sama seperti saat menyesuaikan ruang kerja dengan paket sistem tambahan dengan menambahkan ke packages dalam file dev.nix.

Berikut adalah contoh menambahkan pkgs.nodejs, yang mencakup program biner seperti node, npx, dan 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"
  ''
}

Menambahkan parameter yang dapat dikonfigurasi pengguna

Agar pengguna dapat menyesuaikan titik awal untuk project baru mereka, Anda dapat membuat beberapa template, atau membuat satu template dengan beberapa parameter. Opsi sangatlah tepat jika titik awal Anda yang berbeda hanyalah nilai yang berbeda yang diteruskan ke alat CLI (misalnya --language=js versus --language=ts).

Untuk menambahkan parameter, Anda harus:

1. Jelaskan parameter Anda dalam objek params dari file metadata idx-template.json. Firebase Studio menggunakan informasi dalam file ini untuk menyiapkan UI (seperti kotak centang, drop-down, dan kolom teks) yang ditampilkan kepada pengguna template Anda.
2. Perbarui bootstrap idx-template.nix untuk menggunakan nilai yang dipilih pengguna saat membuat instance template.

Jelaskan parameter Anda di idx-template.json

Berikut adalah contoh menambahkan parameter enum, yang ditampilkan Firebase Studio sebagai menu drop-down atau grup tombol pilihan, bergantung pada jumlah opsi:

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

Karena terdapat dua nilai (JavaScript dan TypeScript), UI akan merender grup tombol pilihan untuk kedua opsi tersebut dan meneruskan nilai ts atau js ke skrip idx-template.nix.

Setiap objek parameter memiliki properti berikut:

Menggunakan parameter value di idx-template.nix

Setelah menentukan objek params dalam file idx-template.json, Anda dapat mulai menyesuaikan skrip bootstrap berdasarkan parameter value yang dipilih pengguna.

Mengikuti contoh di bagian sebelumnya, jika Anda memiliki satu parameter dengan ID language yang merupakan enum dengan kemungkinan nilai ts atau js, Anda dapat menggunakannya seperti ini:

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

Pola umum lainnya adalah menyertakan konten secara kondisional, bergantung pada nilai string. Cara lain untuk menulis contoh sebelumnya adalah:

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

Memilih file yang akan dibuka secara default

Sebaiknya sesuaikan file yang harus dibuka untuk diedit saat ruang kerja baru dibuat dengan template Anda. Misalnya, jika template Anda ditujukan untuk situs dasar, sebaiknya buka file HTML, JavaScript, dan CSS utama.

Untuk menyesuaikan file yang akan dibuka secara default, perbarui file .idx/dev.nix (bukan file idx-template.nix) untuk menyertakan hook ruang kerja onCreate dengan atribut openFiles, seperti berikut:

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

Memilih ikon ruang kerja default

Anda dapat memilih ikon default untuk ruang kerja yang dibuat dengan template Anda, yakni dengan menempatkan file PNG bernama icon.png di samping file dev.nix, di dalam direktori .idx.

Menguji template di ruang kerja baru

Cara termudah untuk menguji template Anda secara menyeluruh adalah dengan membuat ruang kerja baru menggunakan template tersebut. Kunjungi link berikut, dengan mengganti contoh dengan URL repositori GitHub template Anda:

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

Anda dapat menyertakan cabang dan subfolder secara opsional. Semua URL berikut valid, selama dapat diakses secara publik:

• 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

URL ini juga akan Anda bagikan kepada orang lain agar mereka dapat menggunakan template baru Anda, atau URL yang akan Anda tautkan dari tombol "Open in Firebase Studio".

Membagikan template

Setelah memastikan bahwa template Anda berperilaku seperti yang diharapkan, publikasikan template tersebut ke repositori GitHub dan bagikan link yang sama dengan yang Anda gunakan saat membuat ruang kerja untuk pengujian.

Selain itu, untuk mempermudah pengguna menemukan template Anda, tambahkan tombol "Open in Firebase Studio" ke situs atau repositori README.