Buat template kustom

IDX menawarkan berbagai template yang menyertakan semua file, sistem paket (mis. compiler), dan ekstensi yang mungkin digunakan pengguna perlu segera mulai menggunakan bahasa atau kerangka kerja.

Anda mungkin juga ingin membuat template Anda sendiri yang dapat dikonfigurasi oleh pengguna. Contoh:

• Jika membangun framework, library, atau layanan sendiri, Anda dapat yang memungkinkan pengguna untuk cepat menggunakan teknologi Anda, tanpa meninggalkan browser, dengan kekuatan penuh mesin virtual berbasis cloud.

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

• Jika Anda mengajar orang lain, seperti melalui codelab, Anda dapat menghapus beberapa langkah awal untuk siswa Anda dengan untuk codelab Anda sebagai template kustom.

Setelah Anda memiliki template kustom, Anda dapat membuat link untuk agar ditempatkan di situs Anda, repositori Git README file, halaman detail paket (mis. di NPM), atau tempat lain di mana pengguna ingin memulai dengan teknologi Anda.

Catatan: Anda juga dapat membuat link bagi pengguna untuk membuat ruang kerja baru dengan meng-clone repositori Git, yang kurang dapat dikonfigurasi dibandingkan membuat IDX Anda sendiri template, tetapi tidak memerlukan perubahan pada repositori Git.

Prasyarat

Sebelum memulai, pastikan Anda sudah memahami cara menyesuaikan lingkungan dengan file .idx/dev.nix.

Template juga menggunakan bahasa Nix, jadi Anda mungkin ingin memoles beberapa hal dasar, atau menggunakannya sebagai alamat IP internal.

Struktur file template

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

• 

  Membuat ruang kerja baru dari template kustom

  idx-template.json menyertakan metadata untuk template, termasuk nama, deskripsi, dan parameter yang terlihat oleh pengguna dan tersedia untuk pengguna mengonfigurasi template. Misalnya, Anda dapat mengizinkan pengguna memilih dari sejumlah bahasa pemrograman, atau contoh kasus penggunaan. Penggunaan IDX informasi ini untuk mempersiapkan UI yang ditampilkan kepada pengguna saat mereka memilih untuk membuat ruang kerja baru dari template Anda.

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

  1. Membuat direktori kerja ruang kerja baru dan
  2. Menyiapkan lingkungannya dengan membuat file .idx/dev.nix. Perlu diketahui bahwa Anda juga dapat menjalankan alat scaffolding project seperti flutter create atau npm init di skrip ini, atau jalankan skrip kustom yang ditulis dalam Go, Python, Node.js, atau bahasa lain.

  File ini akan dijalankan dengan parameter yang ditentukan oleh pengguna saat mereka mengonfigurasi template.

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

Contoh dasar: mengubah repositori GitHub publik menjadi template

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

• Tidak memiliki parameter yang dapat dikonfigurasi oleh pengguna
• Cukup salin semua file di repositori template Anda (kecuali dua idx-template) ke ruang kerja pengguna. Seharusnya sudah ada Subfolder .idx dengan file dev.nix yang menentukan lingkungan.

Tambahkan file berikut ke repositori GitHub publik (atau subfolder atau cabang) secara efektif mengubah repositori tersebut menjadi {i>template<i} IDX.

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

Catatan: Selain $out, Anda juga bisa mendapatkan ID ruang kerja baru menggunakan $WS_NAME.

Menggunakan paket sistem tambahan dalam skrip bootstrap Anda

Contoh sebelumnya hanya menggunakan perintah POSIX dasar untuk menyalin file ke saat ini. Skrip bootstrap template Anda mungkin memerlukan biner tambahan untuk diinstal, seperti git, node, python3, atau lainnya.

Anda bisa menyediakan paket sistem tambahan untuk skrip bootstrap dengan menentukan packages di file idx-template.nix, seperti yang Anda lakukan menyesuaikan ruang kerja dengan paket sistem tambahan dengan menambahkan ke packages dalam file dev.nix-nya.

Catatan: idx-template.nix selalu menggunakan stable-23.11 Nix channel.

Berikut adalah contoh penambahan pkgs.nodejs yang mencakup 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"
  ''
}

Penting: Skrip bootstrap Anda tidak dapat bersifat interaktif. Jika model menunggu pengguna template, instance akan gagal dibuat dengan benar.

Menambahkan parameter yang dapat dikonfigurasi oleh pengguna

Untuk memungkinkan pengguna menyesuaikan titik awal proyek baru mereka, Anda dapat membuat beberapa template, atau membuat satu template dengan parameter. Ini adalah opsi yang bagus jika titik awal yang berbeda nilai yang diteruskan ke alat CLI (misalnya, --language=js versus --language=ts).

Untuk menambahkan parameter, Anda dapat:

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

Deskripsikan parameter Anda di idx-template.json

Berikut adalah contoh penambahan parameter enum, yang ditampilkan IDX sebagai menu {i>drop-down<i} atau grup tombol pilihan, tergantung pada jumlah opsinya:

{
  "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 ada dua nilai (JavaScript dan TypeScript), UI akan merender grup tombol pilihan untuk kedua opsi dan teruskan nilai ts atau js ke skrip idx-template.nix.

Setiap objek parameter memiliki properti berikut:

PROPERTI	JENIS	DESKRIPSI
id	string	ID unik parameter, mirip dengan nama variabel.
nama	string	Nama tampilan untuk parameter ini.
jenis	string	Menentukan komponen UI yang akan digunakan untuk parameter ini, dan jenis data yang akan diteruskan ke skrip bootstrap. Nilai yang valid adalah: "enum" - Menampilkan grup drop-down atau grup tombol pilihan, dan meneruskan string ke bootstrap "boolean" - Menampilkan kotak centang dan meneruskan true atau false "text" - Menampilkan kolom teks dan meneruskan string
opsi	object	Untuk parameter enum, parameter ini mewakili opsi yang akan ditampilkan kepada pengguna. Misalnya jika opsinya adalah {"js": "JavaScript", ...}, "JavaScript" akan ditampilkan sebagai opsi, dan jika dipilih, nilai parameter ini akan menjadi js.
default	string atau boolean	Menetapkan nilai awal di UI. Untuk parameter enum, parameter ini harus berupa salah satu kunci di options. Untuk parameter boolean, parameter ini harus berupa true atau false.
wajib diisi	boolean	Menunjukkan bahwa parameter ini diperlukan.

Menggunakan parameter value di idx-template.nix

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

Dengan mengikuti contoh di bagian sebelumnya, jika Anda memiliki satu parameter dengan ID language yang merupakan enum dengan kemungkinan nilai ts atau js, Anda dapat menggunakan seperti berikut:

# 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 bersyarat, bergantung pada nilai dari suatu {i>string.<i} Cara lain untuk menulis contoh sebelumnya adalah:

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

Penting: Ingatlah untuk selalu membuat file .idx/dev.nix di $out sebagai bagian dari skrip bootstrap Anda. Jika ruang kerja yang dibuat harus bervariasi berdasarkan parameter yang dikonfigurasi pengguna (mis. termasuk paket sistem yang berbeda, atau menyesuaikan hook onCreate), Anda dapat menggunakan manipulasi string di Nix, atau memanggil mesin pembuat template seperti jinja2.

Pilih file mana yang akan dibuka secara default

Sebaiknya sesuaikan file mana yang harus dibuka untuk pengeditan saat ruang kerja dibuat dengan template Anda. Misalnya, jika {i>template<i} Anda untuk situs web sederhana, Anda mungkin ingin membuka file utama HTML, JavaScript, dan CSS.

Untuk menyesuaikan file mana yang harus dibuka secara default, update file .idx/dev.nix Anda (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 {i>default<i} untuk ruang kerja yang dibuat dengan {i>template<i} Anda, dengan menempatkan file PNG bernama icon.png di samping file dev.nix, di dalam Direktori .idx.

Catatan: File idx-template.json juga menyertakan properti icon opsional, yang harus mengarah ke URL PNG atau SVG publik, jika disediakan. Bidang ini bukan digunakan di BEI, tetapi kemungkinan akan digunakan di masa mendatang, bersama dengan metadata template.

Membuat ruang kerja baru dari template Anda

Cara paling sederhana untuk menguji template Anda secara menyeluruh adalah dengan membuat ruang kerja baru dengannya. Kunjungi tautan berikut, mengganti contoh dengan tautan URL repositori GitHub:

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

Anda dapat menyertakan cabang dan subfolder secara opsional. Semua hal berikut ini valid, selama dapat diakses oleh 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

Ini juga merupakan URL yang akan Anda bagikan dengan orang lain agar mereka dapat menggunakan template, atau URL yang akan Anda tautkan dari opsi "Buka di IDX" .

---

Bagikan template Anda

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

Dan untuk semakin mempermudah pengguna menemukan template Anda, tambahkan ikon "Buka di IDX&quot; ke README atau situs Anda.