blocks.json
blocks.json berada di direktori utama tema atau plugin Anda. File ini memberi tahu CLI tempat menginstal blok dan registry yang harus dicari.
Skema
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.example.com/registry.json",
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}
Bidang
$schema
Opsional. Menunjuk ke Skema JSON untuk pelengkapan otomatis dan validasi editor.
directory
Wajib. Jalur relatif dari blocks.json tempat blok diinstal.
Setiap blok mendapat subfolder sendiri di dalam direktori ini. Jika directory adalah blockstudio dan Anda menambahkan hero, file akan ditempatkan di blockstudio/hero/.
registries
Wajib. Objek yang memetakan nama namespace ke referensi registry.
Kuncinya adalah namespace yang digunakan dalam perintah CLI (npx blockstudio add ui/hero).
Nilainya berupa string URL atau objek dengan url dan headers opsional.
Format string (registry publik):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Format objek (registry terautentikasi):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Kedua format dapat dicampur dalam konfigurasi yang sama. Anda dapat mengonfigurasi sebanyak mungkin registry. Saat menambahkan blok tanpa namespace, CLI mencari di semuanya.
Autentikasi
Registry yang memerlukan autentikasi menggunakan format objek dengan headers.
CLI mengirim header berikut pada setiap permintaan ke registry tersebut, termasuk pengambilan registry.json maupun unduhan file satu per satu.
Token bearer
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Autentikasi dasar
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Header khusus
Header apa pun dapat ditambahkan. Ini berguna untuk kunci API, pengenal organisasi, atau nilai lain yang diminta server registry Anda:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Variabel lingkungan
Nilai header mendukung sintaks ${VAR_NAME} untuk membaca variabel lingkungan.
Dengan begitu, token tidak perlu disimpan dalam kontrol versi.
CLI menyelesaikan variabel lingkungan saat runtime. Jika variabel yang dirujuk belum diatur, CLI berhenti dengan error yang menyebutkan variabel yang belum diatur dan header tempat variabel itu digunakan.
Atur variabel di shell atau lingkungan CI Anda. CLI hanya membaca lingkungan proses; .env tidak memuat file dengan sendirinya:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
Nilai header statis (tanpa ${...}) diteruskan apa adanya.
Penemuan konfigurasi
CLI menelusuri ke atas dari direktori kerja saat ini untuk mencari blocks.json.
Artinya, Anda dapat menjalankan perintah dari subdirektori mana pun di proyek.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Jika blocks.json tidak ditemukan, CLI meminta Anda menjalankan npx blockstudio init.
Contoh: tema dengan dua registry
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.mycompany.com/ui/registry.json",
"internal": "https://blocks.mycompany.com/internal/registry.json"
}
}
Contoh: plugin dengan direktori khusus
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}