Lewati ke konten

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.json diterbitkan oleh pembuat blok. Isinya daftar blok, berkas yang membentuk setiap blok, serta baseUrl untuk mengunduhnya.
  • blocks.json berada 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/:

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

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

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

  • files adalah 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.
  • baseUrl harus berupa URL absolut. CLI memvalidasinya sebagai URL dan menolak nilai relatif. File blok selalu diambil dari baseUrl, tidak pernah dari lokasi relatif terhadap tempat registry.json dimuat.
  • dependencies menamai blok di registri yang sama. Menambahkan tabs akan memasang tab-item terlebih dahulu. Dependensi yang tidak ditemukan atau melingkar akan menghentikan instalasi dengan kesalahan.
  • name wajib ada, tetapi tidak ditampilkan. Perintah dan keluaran menggunakan kunci yang diberikan konsumen kepada registri di blocks.json, yang tidak harus sama.
  • type bersifat informatif. Nilainya dapat berupa blockstudio, create-block, atau wordpress, 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:

Kode
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
  • baseUrl di registry.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:

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

Shell
npx blockstudio init --yes
Kode
Created .../acme-theme/blocks.json

init --yes menulis objek registries kosong. Tambahkan registri di bawah namespace yang ingin Anda ketik dalam perintah:

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

Shell
npx blockstudio list
Kode
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:

Shell
npx blockstudio search tab
Kode
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:

Shell
npx blockstudio add acme/tabs --dry-run
Kode
Would install:
  tab-item (2 files)
  tabs (3 files)

Lalu lakukan instalasi:

Shell
npx blockstudio add acme/tabs
Kode
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Kedua folder kini berada di direktori blockstudio tema, persis seperti di repositori:

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

Shell
npx blockstudio add hero card
Kode
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:

Shell
npx blockstudio add tab-item
Kode
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:

Shell
npx blockstudio add acme/tab-item --dry-run
Kode
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:

Shell
npx blockstudio remove tabs --yes
Kode
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:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

Lalu commit, buat tag, dan push:

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

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

Shell
npx blockstudio list
Kode
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Kode
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. add memuat semua registri di blocks.json sebelum menentukan apa pun, jadi satu registri yang tidak dapat dijangkau akan membuat perintah gagal, bahkan untuk acme/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, --yes memilih yang pertama menurut urutan blocks.json, dan proses noninteraktif akan keluar dengan Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Repositori privat memerlukan header. Gunakan bentuk objek pada entri registri dengan url dan headers. 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