İçeriğe geç

GitHub üzerinde bir blok kayıt defteri yayımlama

Birkaç iyi blok oluşturduktan sonra bunları sonraki projede de kullanmak istersiniz. Temalar arasında klasörleri elle kopyalamak, kopyalar birbirinden ayrışana ve kimse hangi temada düzeltilmiş sürümün bulunduğunu hatırlamayıncaya kadar işe yarar. Her bloğu kendi derlemesine sahip bir pakete sarmak, block.json ve şablon içeren bir klasör için gereğinden fazla törendir.

Arada bir blok kayıt defteri yer alır. Bu, basit HTTP üzerinden sunulan bir registry.json dosyası ve blok klasörleri kümesidir. Kullanıcılar bir CLI komutu çalıştırır; blok kaynağı temalarına kopyalanır ve bundan sonra bu kopyanın sahibi onlar olur. Herkese açık bir depodaki tüm dosyaları ham URL üzerinden GitHub sunduğundan, bir GitHub deposu barındırma için yeterlidir.

Bu kılavuzda dört bloklu acme adlı bir kayıt defteri oluşturulur, acme/acme-blocks deposundan yayımlanır, buradan bir temaya bloklar yüklenir ve git etiketiyle bir sürüm sabitlenir.

npm üzerindeki blockstudio paketi 0.0.1 sürümündedir. Bu sürüm bir yer tutucudur: tek komutu olan add, Adding block: <name> yazdırır ve hiçbir şey indirmeden çıkar. Bu kılavuzdaki komutlar ve çıktılar, Blockstudio deposundaki Registry CLI uygulamasına (packages/registry) aittir; Registry belgelerinde anlatılan CLI budur.

Parçalar nasıl bir araya gelir

Bilinmesi gereken iki dosya vardır:

  • registry.json blok yazarı tarafından yayımlanır. Blokları, her bloğun dosyalarını ve bunları indirmek için bir baseUrl konumunu listeler.
  • blocks.json, tüketicinin temasında veya eklentisinde bulunur. Kullanılacak kayıt defterlerini ve blokların yükleneceği dizini belirtir.

Bir blok yüklediğinizde CLI, blocks.json içindeki her kayıt defterinden verileri alır, bloğu bulur, bağımlılıklarını çözümler, listelenen her dosyayı {baseUrl}/{block}/{file} üzerinden indirir ve {directory}/{block}/{file} konumuna yazar. Hiçbir şeyi dönüştürmez; bu nedenle diskteki dosyalar depodaki dosyalarla tamamen aynıdır.

1. adım: Depoyu yapılandırma

Kök dizinde bir registry.json ve blocks/ altında her blok için bir klasör bulunan bir depo oluşturun:

Kod
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

Klasör adı, kayıt defterindeki blok adıdır ve tüketicinin temasındaki klasör adı olur. Yüklenen klasörün kolayca tanınması için block.json içindeki blok adının ikinci kısmıyla aynı tutun (acme/hero, hero/ içinde bulunur).

2. adım: Blokları yazma

Her klasör sıradan bir Blockstudio bloğudur. Hero bloğunda tek bir alan vardır:

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 aynı kalıbı izler ve bir style.scss ekler. tabs, <InnerBlocks allowedBlocks='["acme/tab-item"]' /> öğesini oluşturur; tab-item ise "parent": ["acme/tabs"] öğesini bildirir. Bu nedenle tabs, tab-item olmadan kullanışlı değildir. Kayıt defteri bu ilişkiyi sonraki adımda ifade eder.

Bu blokların hiçbir özelliği kayıt defterine özgü değildir. CLI klasörleri kopyalar; dolayısıyla @wordpress/create-block ile oluşturulan veya düz PHP ile kaydedilen bir blok da aynı şekilde yayımlanabilir.

3. adım: registry.json yazma

registry.json, CLI öğesinin indirmesi gereken her bloğu ve dosyayı listeler:

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"]
    }
  ]
}

Bu dosyanın çalışıp çalışmayacağını belirleyen birkaç kural vardır:

  • files açık bir listedir. CLI yalnızca bu yolları indirir, başka hiçbir şeyi indirmez. Glob kullanımı yoktur; bu nedenle yeni bir varlık ancak buraya eklendiğinde pakete dahil olur. Yollar alt dizinler içerebilir; bu dizinler kurulum sırasında oluşturulur.
  • baseUrl mutlak bir URL olmalıdır. CLI bunu URL olarak doğrular ve göreli değerleri reddeder. Blok dosyaları her zaman baseUrl üzerinden alınır; registry.json nereden yüklenmiş olursa olsun, ona göreli bir konumdan alınmaz.
  • dependencies aynı kayıt defterindeki blokları adlandırmalıdır. tabs eklemek önce tab-item kurar. Eksik ve döngüsel bağımlılıklar kurulumu durdurur ve hata verir.
  • name gereklidir ancak görüntülenmez. Komutlar ve çıktılar, kullanıcının kayıt defterine blocks.json verdiği anahtarı kullanır; bu anahtarın aynı olması gerekmez.
  • type yalnızca bilgi amaçlıdır. blockstudio, create-block veya wordpress değerini kabul eder ve CLI işleyişini değiştirmez.

CLI her indirmede dosyanın tamamını doğrular ve başarısız olan her alanı bildirir; böylece bir yazım hatası, herhangi bir dosya indirilmeden önce görünür. $schema satırı aynı denetimleri düzenleyicinizde yapmanızı sağlar.

Adım 4: Ham URL’ler üzerinden yayımlayın

Depoyu GitHub platformuna gönderip değişiklikleri itin. Böylece herkese açık depodaki her dosyaya şu adresten erişilebilir:

Kod
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> bir dal, etiket veya commit SHA’sıdır. Bu kayıt defteri için önemli olan iki URL şunlardır:

  • Tüketicilerin yapılandırdığı kayıt defteri URL: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • registry.json içindeki baseUrl: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Bu baseUrl ile hero öğesinin index.php https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php adresinden alınır. Ham sunucu, CLI gereksinimi olan GitHub HTML sayfası yerine dosya içeriğini döndürür. Yanlış sahip, depo veya ref, ilk komutta 404 olarak ortaya çıkar:

Kod
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

Adım 5: Blokları bir temaya kurun

Kullanan temanın kök dizininde blocks.json oluşturun:

Kabuk
npx blockstudio init --yes
Kod
Created .../acme-theme/blocks.json

init --yes boş bir registries nesnesi yazar. Kayıt defterini, komutlarda yazmak istediğiniz ad alanı altında ekleyin:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
  }
}

Aynı soruları (blok dizini, kayıt defteri adları ve URL’leri) etkileşimli olarak yanıtlamak için terminalde --yes olmadan init çalıştırın.

Kayıt defterinin çözümlendiğini denetleyin:

Kabuk
npx blockstudio list
Kod
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; adlar, başlıklar ve açıklamalardaki büyük/küçük harfe duyarsız bir alt dizeyle eşleşir:

Kabuk
npx blockstudio search tab
Kod
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

--dry-run ile kurulumu önizleyin. Bağımlılık önce kurulduğundan listede de önce yer alır:

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

Ardından gerçekten kurun:

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

Her iki klasör de artık temanın blockstudio dizininde, depodakiyle tamamen aynı şekilde bulunuyor:

Kod
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Yapılandırılmış tek bir kayıt defterinde blok varsa ad alanını belirtmeden bırakabilir, aynı anda birden çok blok aktarabilirsiniz:

Kabuk
npx blockstudio add hero card
Kod
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio yeni klasörleri temadaki diğer bloklar gibi keşfeder.

Kurulu blokları güncelleme

Kurulan dosyalar birer kopyadır. Hangi sürümü kurduğunuzu izleyen bir şey yoktur ve CLI bir bloğu kendiliğinden güncellemez. Daha yeni bir sürümü almak için bloğu yeniden ekleyin. Terminal olmadan veya CI’da, mevcut bir klasör komutun çalışmasını engeller:

Kabuk
npx blockstudio add tab-item
Kod
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

Terminalde ise CLI üzerine yazmadan önce sorar. --dry-run değiştirilecek klasörleri bildirir, --yes ise bunların yerine yenilerini koyar:

Kabuk
npx blockstudio add acme/tab-item --dry-run
Kod
Would overwrite tab-item
Would install:
  tab-item (2 files)

Üzerine yazma, listelenen dosyaları kayıt defterindeki sürümleriyle değiştirir. Bu yüzden önce yerel değişiklikleri commit edin ve sonucu git diff ile gözden geçirin.

Kaldırmak için klasörü adına göre silin:

Kabuk
npx blockstudio remove tabs --yes
Kod
Removed tabs

remove, namespace/block yerine klasör adını alır. Bağımlılıkları kaldırmaz; dolayısıyla tabs kaldırıldıktan sonra da tab-item kurulu kalır.

git ref’leriyle sürümleme

CLI içinde bir sürüm alanı veya sürüm bayrağı yoktur. Ne indireceğini tamamen URL’ler belirler; GitHub üzerinde ise URL içindeki ref sürümdür. main öğesine yönlendiren bir tüketici, kurulum anında main içeriğinde ne varsa onu alır.

Değişmeyecek bir sürümü yayımlamak için etiket üzerindeki registry.json de o etiketten indirme yapmalıdır. Etiketlemeden önce baseUrl değerini etikete ayarlayın:

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

Ardından commit edin, etiketleyin ve gönderin:

Kabuk
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

Sonrasında baseUrl değerini yeniden main yapıp commit edin; böylece dal güncel dosyaları sunmaya devam eder. İlk adımı atlarsanız etikete sabitlenmiş tüketici, etiketli blok listesini alır ancak dosyaları main üzerinden indirir.

Tüketiciler kayıt defteri URL alanında etiketi kullanarak sürümü sabitler:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

Bu örnekte v1.0.0, tabs ve tab-item mevcut olmadan önce etiketlendi; bu nedenle sabitlenmiş kayıt defterinde yalnızca ilk iki blok bulunur:

Kabuk
npx blockstudio list
Kod
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Kabuk
npx blockstudio add acme/tabs
Kod
Block "tabs" not found in registry "acme".

Kayıt defteri URL alanında commit SHA’sı da kullanılabilir; ancak bir commit kendi SHA’sını baseUrl içine koyamaz. Bu nedenle SHA ile sabitleme blok listesini sabitlerken dosyalar, o commit’in baseUrl içinde adlandırdığı ref’ten gelmeye devam eder. Sürümler için etiketleri tercih edin.

Akılda tutulması gerekenler

  • Önce her kayıt defteri alınır. add herhangi bir şeyi çözümlemeden önce blocks.json içindeki tüm kayıt defterlerini yükler; bu yüzden erişilemeyen tek bir kayıt defteri bile komutun, acme/hero için dahi başarısız olmasına yol açar. Artık kullanmadığınız kayıt defterlerini kaldırın.
  • Belirsiz adlar için ad alanı gerekir. İki kayıt defterinde de hero varsa terminal oturumu hangisinin kullanılacağını sorar, --yes ise blocks.json sırasındaki ilkini alır; etkileşimsiz çalıştırma da Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero ile sonlanır.
  • Özel depolar için başlık gerekir. url ve headers içeren bir kayıt defteri girdisinin nesne biçimini kullanın. Başlık değerlerinde ortamdan okunan ${VAR} yer tutucuları kullanılabilir. CLI, kayıt defteri isteğinde ve her dosya indirmesinde bu başlıkları gönderir. Belirteç ayarı için GitHub barındırma sayfasına bakın.

Sonraki adımlar

  • Kayıt defterine genel bakış: kayıt defterinin ne olduğunu ve CLI işleyişini açıklar
  • registry.json: manifestin tüm alanlarını açıklar
  • blocks.json: tüketici yapılandırması, kimlik doğrulama ve yapılandırma keşfini açıklar
  • ekle: ad alanı çözümleme, bağımlılıklar ve üzerine yazma davranışını açıklar
  • GitHub barındırma: GitHub Pages ve özel depoları açıklar
  • Özel sunucu: kendi altyapınızdan kayıt defteri sunmayı açıklar