IDX menawarkan berbagai template bawaan yang mencakup semua file, paket sistem (mis. compiler), dan ekstensi yang mungkin diperlukan pengguna untuk mulai menggunakan bahasa atau framework dengan cepat.
Anda mungkin juga ingin membuat template Anda sendiri yang dapat dikonfigurasi oleh pengguna. Contoh:
Jika Anda membangun framework, library, atau layanan sendiri, Anda dapat mengizinkan pengguna untuk segera mulai menggunakan teknologi Anda, tanpa meninggalkan browser, dengan kecanggihan mesin virtual berbasis cloud.
Jika memiliki technology stack pilihan untuk project, Anda dapat menyederhanakan proses Anda sendiri untuk memulai project baru dengan template kustom.
Jika Anda mengajar orang lain, seperti melalui codelab, Anda dapat menghapus beberapa langkah awal untuk siswa dengan mengonfigurasi titik awal codelab Anda sebagai template kustom.
Setelah template kustom siap, Anda dapat membuat link untuknya untuk ditempatkan di situs Anda, file README
repositori Git, halaman detail paket (mis. di NPM), atau tempat lain tempat pengguna ingin mulai menggunakan teknologi Anda.
Prasyarat
Sebelum memulai, pastikan Anda sudah memahami cara menyesuaikan lingkungan dengan file .idx/dev.nix
.
Template juga menggunakan bahasa Nix, jadi Anda mungkin ingin mempelajari beberapa dasar-dasarnya, atau membuatnya berguna sebagai referensi.
Struktur file template
Template adalah repositori GitHub publik (atau folder atau cabang dalam repositori) yang berisi minimal dua file:
-
idx-template.json
menyertakan metadata untuk template, termasuk nama, deskripsi, dan parameternya yang terlihat oleh pengguna yang tersedia bagi pengguna untuk mengonfigurasi template. Misalnya, Anda dapat mengizinkan pengguna memilih dari sejumlah bahasa pemrograman, atau contoh kasus penggunaan. IDX 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 (dibungkus dalam fungsi Nix) yang bertanggung jawab untuk:- Membuat direktori kerja ruang kerja baru dan
- Menyiapkan lingkungannya dengan membuat file
.idx/dev.nix
. Perhatikan bahwa Anda juga dapat menjalankan alat scaffolding project sepertiflutter create
ataunpm 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 mereka mengonfigurasi 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
akhir, atau bahkan menyertakan semua file scaffolding
langsung di repositori.
Contoh dasar: mengubah repositori GitHub publik menjadi template
Sebelum membahas 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 untuk dua file
idx-template
) ke ruang kerja pengguna. Seharusnya sudah ada subfolder.idx
dengan filedev.nix
yang menentukan lingkungan.
Menambahkan file berikut ke repositori GitHub publik (atau subfolder atau cabang) akan secara efektif mengubah repositori tersebut menjadi template 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}
'';
}
Menggunakan paket sistem tambahan dalam skrip bootstrap
Anda
Contoh sebelumnya hanya menggunakan perintah POSIX dasar untuk menyalin file ke tempat
yang tepat. Skrip bootstrap
template Anda mungkin memerlukan biner tambahan untuk diinstal, seperti git
, node
, python3
, atau lainnya.
Anda dapat menyediakan paket sistem tambahan untuk skrip bootstrap dengan menentukan packages
di file idx-template.nix
, sama seperti Anda menyesuaikan ruang kerja dengan paket sistem tambahan dengan menambahkannya ke packages
di file dev.nix
-nya.
Berikut adalah contoh penambahan pkgs.nodejs
yang menyertakan 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 oleh pengguna
Untuk memungkinkan pengguna menyesuaikan titik awal project baru mereka, Anda dapat membuat beberapa template, atau membuat satu template dengan parameter.
Teknik ini adalah opsi yang bagus jika titik awal Anda yang berbeda hanyalah nilai berbeda yang diteruskan ke alat CLI (misalnya, --language=js
versus --language=ts
).
Untuk menambahkan parameter, Anda dapat:
- Jelaskan parameter Anda dalam objek
params
dari file metadataidx-template.json
Anda. IDX menggunakan informasi dalam file ini untuk menyiapkan UI (seperti kotak centang, drop-down, dan kolom teks) yang ditampilkan kepada pengguna template Anda. - Update 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 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 ada 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:
PROPERTI | TYPE | DESKRIPSI |
---|---|---|
id | string |
ID unik parameter, mirip dengan nama variabel. |
name | string |
Nama tampilan untuk parameter ini. |
tipe | string |
Menentukan komponen UI yang akan digunakan untuk parameter ini, dan jenis data yang akan diteruskan ke skrip bootstrap. Nilai yang valid adalah:
|
opsi | object |
Untuk parameter enum , parameter ini merepresentasikan opsi yang akan ditampilkan kepada pengguna. Misalnya, jika opsinya {"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 | boolean |
Menunjukkan bahwa parameter ini diperlukan. |
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.
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 menggunakannya
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 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" }
Pilih file mana yang akan dibuka secara default
Sebaiknya sesuaikan file mana 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 mana yang harus dibuka secara default, perbarui 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 = { ... };
};
}
Membuat ruang kerja baru dari template Anda
Cara paling sederhana untuk menguji template Anda secara menyeluruh adalah dengan membuat ruang kerja baru menggunakan template tersebut. Buka link berikut, ganti 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 hal 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
Ini juga merupakan URL yang akan Anda bagikan kepada orang lain agar mereka dapat menggunakan template baru Anda, atau URL yang akan Anda tautkan dari tombol "Buka di IDX".
Bagikan template Anda
Setelah mengonfirmasi bahwa template Anda berperilaku seperti yang diharapkan, publikasikan ke repositori GitHub dan bagikan link yang sama dengan yang Anda gunakan saat membuat ruang kerja untuk pengujian.
Agar pengguna lebih mudah menemukan template Anda, tambahkan tombol"Buka di IDX" ke README atau situs web Anda.