registry.json
registry.json adalah file JSON yang dihosting di URL. File ini mencantumkan semua blok yang tersedia di registry, metadata, dependensi, dan manifest filenya.
Skema
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "ui",
"description": "Core UI blocks for Blockstudio projects.",
"baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
"blocks": [
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with accessible keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": [
"block.json",
"index.php",
"style.scss"
]
}
]
}
Bidang tingkat atas
name
Wajib. Pengenal registry. CLI memvalidasinya tetapi tidak menampilkannya: perintah dan output menggunakan kunci yang dipilih pengguna untuk registry di blocks.json.
description
Opsional. Deskripsi singkat tentang isi registry ini.
baseUrl
Wajib. URL dasar untuk mengunduh file blok. Harus berupa URL yang valid.
File diambil dengan menggabungkan URL dasar, nama blok, dan jalur file: {baseUrl}/{block.name}/{file}.
Misalnya, jika baseUrl diatur ke https://raw.githubusercontent.com/acme/blocks/main/blocks dan blok bernama tabs memiliki file index.php, CLI akan mengambil:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Bidang blok
name
Wajib. Nama folder blok. Ini adalah pengenal yang digunakan dalam perintah CLI dan menjadi nama folder di disk.
title
Opsional. Nama yang mudah dibaca dan ditampilkan dalam output list dan search.
description
Opsional. Deskripsi satu baris yang ditampilkan dalam hasil search.
category
Opsional. Label pengelompokan untuk output list.
type
Opsional. Salah satu dari blockstudio, create-block, atau wordpress.
Informasi ini hanya untuk referensi. CLI tidak mengubah perilaku berdasarkan jenis blok. Perintah selalu mengunduh dan menyalin file yang tercantum di files.
dependencies
Opsional. Array nama blok lain di registry yang sama dan harus diinstal bersama blok ini.
Saat pengguna menambahkan blok dengan dependensi, CLI menyelesaikan seluruh pohon dependensi dan menginstal semuanya dalam urutan yang benar. Dependensi melingkar akan dideteksi dan ditolak.
Dependensi harus berada di registry yang sama. Dependensi lintas registry tidak didukung.
files
Wajib. Array jalur file relatif terhadap folder blok. Sedikitnya satu file wajib ada.
Inilah file persis yang diunduh CLI dan ditulis ke disk. Jalur dapat mencakup subdirektori:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Resolusi file
Untuk setiap file dalam manifest blok, CLI menyusun URL unduhan:
{baseUrl}/{block.name}/{file}
Lalu menulisnya ke:
{directory}/{block.name}/{file}
Struktur direktori di dalam folder blok tetap dipertahankan. Jika jalur file berisi subdirektori, direktori tersebut dibuat secara otomatis.
File selalu diambil dari baseUrl di dalam registry.json, bukan dari lokasi yang relatif terhadap URL registry di blocks.json.
Validasi
CLI memvalidasi registry.json terhadap skema Zod setiap kali data diambil.
Registry yang tidak valid akan menghasilkan pesan error yang jelas dan menyebutkan bidang yang gagal divalidasi.
Bidang wajib yang hilang, array blocks atau files yang kosong, URL tidak valid, dan nilai type yang tidak dikenal akan terdeteksi sebelum file apa pun diunduh.