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.jsonblok yazarı tarafından yayımlanır. Blokları, her bloğun dosyalarını ve bunları indirmek için birbaseUrlkonumunu 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:
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:
{
"$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 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:
{
"$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:
filesaçı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.baseUrlmutlak bir URL olmalıdır. CLI bunu URL olarak doğrular ve göreli değerleri reddeder. Blok dosyaları her zamanbaseUrlüzerinden alınır;registry.jsonnereden yüklenmiş olursa olsun, ona göreli bir konumdan alınmaz.dependenciesaynı kayıt defterindeki blokları adlandırmalıdır.tabseklemek öncetab-itemkurar. Eksik ve döngüsel bağımlılıklar kurulumu durdurur ve hata verir.namegereklidir ancak görüntülenmez. Komutlar ve çıktılar, kullanıcının kayıt defterineblocks.jsonverdiği anahtarı kullanır; bu anahtarın aynı olması gerekmez.typeyalnızca bilgi amaçlıdır.blockstudio,create-blockveyawordpressdeğ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:
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.jsoniçindekibaseUrl: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:
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:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes boş bir registries nesnesi yazar. Kayıt defterini, komutlarda yazmak istediğiniz ad alanı altında ekleyin:
{
"$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:
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; adlar, başlıklar ve açıklamalardaki büyük/küçük harfe duyarsız bir alt dizeyle eşleşir:
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.
--dry-run ile kurulumu önizleyin. Bağımlılık önce kurulduğundan listede de önce yer alır:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Ardından gerçekten kurun:
npx blockstudio add acme/tabs
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:
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:
npx blockstudio add hero card
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:
npx blockstudio add tab-item
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:
npx blockstudio add acme/tab-item --dry-run
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:
npx blockstudio remove tabs --yes
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:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Ardından commit edin, etiketleyin ve gönderin:
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:
{
"$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:
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".
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.
addherhangi bir şeyi çözümlemeden önceblocks.jsoniçindeki tüm kayıt defterlerini yükler; bu yüzden erişilemeyen tek bir kayıt defteri bile komutun,acme/heroiç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
herovarsa terminal oturumu hangisinin kullanılacağını sorar,--yesiseblocks.jsonsırasındaki ilkini alır; etkileşimsiz çalıştırma daBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/heroile sonlanır. - Özel depolar için başlık gerekir.
urlveheadersiç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