Menerbitkan Registri Blok di GitHub
Setelah membuat beberapa blok yang bagus, Anda tentu ingin menggunakannya di proyek berikutnya juga. Menyalin folder antar-tema secara manual bisa dilakukan sampai salinannya berbeda dan tidak ada yang ingat tema mana yang memiliki versi perbaikan. Membungkus setiap blok dalam paket dengan proses build sendiri terlalu merepotkan untuk sebuah folder yang berisi block.json dan templat.
Registri blok menjadi perantara. Isinya adalah berkas registry.json dan sekumpulan folder blok, yang disajikan melalui HTTP biasa. Pengguna menjalankan perintah CLI, sumber blok disalin ke tema mereka, lalu mereka mengelola salinan tersebut sendiri. Repositori GitHub cukup untuk menghostingnya, karena GitHub menyajikan setiap berkas dalam repositori publik melalui URL mentah.
Panduan ini membuat registri bernama acme dengan empat blok, menerbitkannya dari repositori acme/acme-blocks, memasang blok darinya ke dalam tema, dan menetapkan rilis melalui tag git.
Paket blockstudio di npm berada pada versi 0.0.1. Rilis tersebut hanyalah placeholder: satu-satunya perintahnya, add, mencetak Adding block: <name> lalu keluar tanpa mengambil apa pun. Perintah dan keluaran dalam panduan ini berasal dari registri CLI di repositori Blockstudio (packages/registry), yang merupakan CLI yang dijelaskan dalam dokumen Registri.
Cara komponen saling terkait
Ada dua berkas yang perlu diketahui:
registry.jsonditerbitkan oleh pembuat blok. Isinya daftar blok, berkas yang membentuk setiap blok, sertabaseUrluntuk mengunduhnya.blocks.jsonberada di tema atau plugin pengguna. Berkas ini menyebut registri yang akan digunakan dan direktori tempat blok dipasang.
Saat Anda memasang blok, CLI mengambil setiap registri di blocks.json, mencari bloknya, menyelesaikan dependensinya, mengunduh setiap berkas yang tercantum dari {baseUrl}/{block}/{file}, lalu menulisnya ke {directory}/{block}/{file}. Tidak ada yang diubah, sehingga berkas di disk sama persis dengan berkas dalam repositori.
Langkah 1: Susun repositori
Buat repositori dengan registry.json di root dan satu folder untuk setiap blok di dalam blocks/:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
tabs/
block.json
index.php
style.scss
tab-item/
block.json
index.php
Nama folder adalah nama blok di registri dan menjadi nama folder di tema pengguna. Samakan dengan bagian kedua nama blok di block.json (acme/hero berada di hero/), agar folder yang terpasang mudah dikenali.
Langkah 2: Tulis blok
Setiap folder adalah blok Blockstudio biasa. Blok hero memiliki satu kolom:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"category": "design",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build faster"
}
]
}
}
<section useBlockProps class="acme-hero">
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>
card mengikuti pola yang sama dan menambahkan style.scss. tabs merender <InnerBlocks allowedBlocks='["acme/tab-item"]' />, dan tab-item mendeklarasikan "parent": ["acme/tabs"], sehingga tabs tidak berguna tanpa tab-item. Registri menyatakan hubungan tersebut pada langkah berikutnya.
Tidak ada yang khusus untuk registri pada blok-blok ini. CLI menyalin folder, jadi blok yang dibuat dengan @wordpress/create-block atau didaftarkan dengan PHP biasa dapat diterbitkan dengan cara yang sama.
Langkah 3: Tulis registry.json
registry.json mencantumkan setiap blok dan berkas yang harus diunduh oleh CLI:
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "acme",
"description": "Acme block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"description": "Full-width hero section with a heading.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"description": "Content card with a title.",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tab-item",
"title": "Tab Item",
"description": "Single tab panel used inside Tabs.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
}
]
}
Beberapa aturan menentukan apakah berkas ini berfungsi:
filesadalah daftar eksplisit. CLI mengunduh tepat jalur-jalur ini dan tidak ada yang lain. Tidak ada pencocokan pola glob, jadi aset baru hanya akan disertakan setelah Anda menambahkannya di sini. Jalur dapat berisi subdirektori, yang akan dibuat saat instalasi.baseUrlharus berupa URL absolut. CLI memvalidasinya sebagai URL dan menolak nilai relatif. File blok selalu diambil daribaseUrl, tidak pernah dari lokasi relatif terhadap tempatregistry.jsondimuat.dependenciesmenamai blok di registri yang sama. Menambahkantabsakan memasangtab-itemterlebih dahulu. Dependensi yang tidak ditemukan atau melingkar akan menghentikan instalasi dengan kesalahan.namewajib ada, tetapi tidak ditampilkan. Perintah dan keluaran menggunakan kunci yang diberikan konsumen kepada registri diblocks.json, yang tidak harus sama.typebersifat informatif. Nilainya dapat berupablockstudio,create-block, atauwordpress, dan tidak mengubah fungsi CLI.
CLI memvalidasi seluruh file setiap kali diambil dan melaporkan setiap kolom yang gagal, sehingga salah ketik terdeteksi sebelum file apa pun diunduh. Baris $schema memberikan pemeriksaan yang sama di editor Anda.
Langkah 4: Publikasikan melalui URL raw
Commit dan push repositori ke GitHub. Setiap file di repositori publik kemudian tersedia di:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref> adalah branch, tag, atau SHA commit. Untuk registri ini, ada dua URL yang penting:
- Registri URL yang dikonfigurasi konsumen:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json baseUrldiregistry.json:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
Dengan baseUrl tersebut, index.php dari hero diambil dari
https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php.
Host raw mengembalikan konten file, bukan halaman GitHub HTML, sesuai kebutuhan CLI. Pemilik, repositori, atau ref yang salah akan memunculkan 404 pada perintah pertama:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
Langkah 5: Pasang blok di tema
Di akar tema yang menggunakan registri, buat blocks.json:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes menulis objek registries kosong. Tambahkan registri di bawah namespace yang ingin Anda ketik dalam perintah:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Jalankan init tanpa --yes di terminal untuk menjawab pertanyaan yang sama secara interaktif (direktori blok, nama dan URL registri).
Periksa apakah registri dapat ditemukan:
npx blockstudio list
acme (4 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
tabs Tabs layout blockstudio
tab-item Tab Item layout blockstudio
search mencocokkan substring tanpa membedakan huruf besar-kecil pada nama, judul, dan deskripsi:
npx blockstudio search tab
Results for "tab"
acme/tabs - Tabs
Tabbed content with keyboard navigation.
acme/tab-item - Tab Item
Single tab panel used inside Tabs.
Pratinjau instalasi dengan --dry-run. Dependensi dicantumkan lebih dahulu karena dipasang lebih dahulu:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Lalu lakukan instalasi:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
Kedua folder kini berada di direktori blockstudio tema, persis seperti di repositori:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
Anda dapat menghilangkan namespace jika hanya satu registri yang dikonfigurasi memiliki blok tersebut, dan memasang beberapa blok sekaligus:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudio menemukan folder baru seperti blok lain mana pun di tema.
Memperbarui blok yang terpasang
File yang terpasang adalah salinan. Tidak ada yang melacak versi yang Anda pasang, dan CLI tidak pernah memperbarui blok dengan sendirinya. Untuk mengambil versi yang lebih baru, tambahkan blok itu lagi. Tanpa terminal, atau di CI, folder yang sudah ada akan menghentikan perintah:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
Di terminal, CLI akan bertanya sebelum menimpa. --dry-run melaporkan folder yang akan diganti, dan --yes menggantinya:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
Penimpaan mengganti file yang tercantum dengan versi dari registri, jadi commit perubahan lokal terlebih dahulu dan tinjau hasilnya dengan git diff.
Untuk mencopot pemasangan, hapus folder berdasarkan namanya:
npx blockstudio remove tabs --yes
Removed tabs
remove menerima nama folder, bukan namespace/block. Perintah ini tidak menghapus dependensi, jadi tab-item tetap terpasang setelah tabs dihapus.
Mengelola versi dengan ref git
CLI tidak memiliki kolom versi maupun flag versi. File yang diambil sepenuhnya ditentukan oleh URL, dan di GitHub ref dalam URL adalah versinya. Konsumen yang mengarah ke main akan mendapatkan apa pun yang ada di main saat instalasi.
Untuk memublikasikan rilis yang versinya tetap, registry.json di tag juga harus mengunduh dari tag tersebut. Sebelum membuat tag, atur baseUrl ke tag itu:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Lalu commit, buat tag, dan push:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
Setelah itu, kembalikan baseUrl ke main dan commit agar branch tetap menyajikan file terbaru. Jika langkah pertama dilewati, konsumen yang dikunci ke tag akan mendapatkan daftar blok bertag, tetapi mengunduh file dari main.
Konsumen mengunci versi dengan menggunakan tag di URL registri mereka:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
Dalam contoh ini, v1.0.0 diberi tag sebelum tabs dan tab-item ada, jadi registri yang dikunci hanya menawarkan dua blok awal:
npx blockstudio list
acme (2 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
npx blockstudio add acme/tabs
Block "tabs" not found in registry "acme".
SHA commit juga dapat digunakan di URL registri, tetapi commit tidak dapat mencantumkan SHA-nya sendiri di baseUrl. Jadi, penguncian berdasarkan SHA menetapkan daftar blok, sementara file tetap diambil dari ref apa pun yang disebutkan oleh baseUrl commit tersebut. Karena itu, gunakan tag untuk rilis.
Hal yang perlu diingat
- Setiap registri diambil terlebih dahulu.
addmemuat semua registri diblocks.jsonsebelum menentukan apa pun, jadi satu registri yang tidak dapat dijangkau akan membuat perintah gagal, bahkan untukacme/hero. Hapus registri yang tidak lagi Anda gunakan. - Nama ambigu memerlukan namespace. Jika dua registri sama-sama memiliki
hero, sesi terminal akan menanyakan mana yang akan digunakan,--yesmemilih yang pertama menurut urutanblocks.json, dan proses noninteraktif akan keluar denganBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero. - Repositori privat memerlukan header. Gunakan bentuk objek pada entri registri dengan
urldanheaders. Nilai header mendukung placeholder${VAR}yang dibaca dari lingkungan, dan CLI mengirim header tersebut saat mengambil registri dan mengunduh setiap file. Lihat hosting GitHub untuk penyiapan token.
Langkah berikutnya
- Ikhtisar registri: apa itu registri dan cara kerja CLI
- registry.json: setiap kolom manifes
- blocks.json: konfigurasi konsumen, autentikasi, dan penemuan konfigurasi
- add: resolusi namespace, dependensi, dan perilaku penimpaan
- Hosting GitHub: GitHub Pages dan repositori privat
- Server kustom: menyajikan registri dari infrastruktur Anda sendiri