Lewati ke konten

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

JSON
{
  "$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:

Kode
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:

JSON
{
  "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:

Kode
{baseUrl}/{block.name}/{file}

Lalu menulisnya ke:

Kode
{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.