Hoppa till innehåll

Publicera ett blockregister på GitHub

När du har byggt några bra block vill du även ha dem i nästa projekt. Att kopiera mappar manuellt mellan teman fungerar tills kopiorna skiljer sig åt och ingen längre minns vilket tema som har den rättade versionen. Att paketera varje block i ett eget paket med en egen byggprocess innebär mycket omständligt arbete för en mapp som innehåller ett block.json och en mall.

Ett blockregister fyller mellanrummet. Det är en fil av typen registry.json och en uppsättning blockmappar som levereras via vanlig HTTP. Användarna kör ett CLI-kommando, blockkällan kopieras till deras tema och därefter ansvarar de själva för kopian. Ett GitHub-arkiv räcker för att stå värd för ett register, eftersom GitHub levererar alla filer i ett offentligt arkiv via en rå URL.

Den här guiden bygger ett register som heter acme med fyra block, publicerar det från arkivet acme/acme-blocks, installerar block därifrån i ett tema och låser en utgåva via en git-tagg.

Paketet blockstudio på npm har version 0.0.1. Den utgåvan är en platshållare: dess enda kommando, add, skriver ut Adding block: <name> och avslutas utan att hämta något. Kommandona och utdata i den här guiden kommer från registret CLI i arkivet Blockstudio (packages/registry), som är det register som beskrivs i dokumentationen CLIRegistry docs.

Så hänger delarna ihop

Det finns två filer att känna till:

  • registry.json publiceras av blockförfattaren. Den listar blocken, filerna som varje block består av och en baseUrl för att hämta dem.
  • blocks.json finns i användarens tema eller tillägg. Den anger vilka register som ska användas och vilken katalog block installeras i.

När du installerar ett block hämtar CLI varje register i blocks.json, hittar blocket, löser dess beroenden, laddar ned varje listad fil från {baseUrl}/{block}/{file} och skriver den till {directory}/{block}/{file}. Inget omvandlas, så filerna på disken är exakt desamma som i arkivet.

Steg 1: Strukturera arkivet

Skapa ett arkiv med en registry.json i roten och en mapp per block under blocks/:

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

Mappnamnet är blockets namn i registret och blir mappnamnet i användarens tema. Se till att det stämmer exakt med den andra delen av blocknamnet i block.json (acme/hero finns i hero/), så blir den installerade mappen lätt att känna igen.

Steg 2: Skriv blocken

Varje mapp innehåller ett vanligt Blockstudio-block. Hero-blocket har ett fält:

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 följer samma mönster och lägger till en style.scss. tabs renderar <InnerBlocks allowedBlocks='["acme/tab-item"]' />, och tab-item deklarerar "parent": ["acme/tabs"], så tabs är inte användbart utan tab-item. Registret uttrycker sambandet i nästa steg.

Inget i dessa block är specifikt för ett register. CLI kopierar mappar, så block som byggts med @wordpress/create-block eller registrerats med vanlig PHP kan publiceras på samma sätt.

Steg 3: Skriv registry.json

registry.json listar alla block och filer som CLI ska hämta:

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

Det finns några regler som avgör om den här filen fungerar:

  • files är en explicit lista. CLI laddar ner exakt dessa sökvägar och inget annat. Ingen globning används, så en ny resurs inkluderas först när du lägger till den här. Sökvägar kan innehålla underkataloger, som skapas vid installationen.
  • baseUrl måste vara en absolut URL. CLI validerar den som en URL och avvisar relativa värden. Blockfiler hämtas alltid från baseUrl, aldrig från en plats relativ till var registry.json lästes in.
  • dependencies-namn anger block i samma register. Om du lägger till tabs installeras tab-item först. Saknade och cirkulära beroenden avbryter installationen med ett fel.
  • name krävs men visas inte. Kommandon och utdata använder nyckeln som konsumenten anger för registret i blocks.json, och den behöver inte stämma överens.
  • type är informativ. Den godtar blockstudio, create-block eller wordpress och påverkar inte vad CLI gör.

CLI validerar hela filen vid varje hämtning och rapporterar varje fält med fel, så ett stavfel upptäcks innan någon fil laddas ner. Raden $schema ger dig samma kontroller i redigeraren.

Steg 4: Publicera via råa URL:er

Commit:a och skicka repot till GitHub. Därefter finns varje fil i ett offentligt repo tillgänglig på:

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

<ref> är en branch, en tagg eller en commit-SHA. För det här registret är två URL:er viktiga:

  • Registrets URL som konsumenter konfigurerar: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • baseUrl i registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Med den baseUrl hämtas index.php för hero från https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Den råa värdtjänsten returnerar filinnehållet i stället för sidan GitHub HTML, vilket är vad CLI behöver. Fel ägare, repo eller ref märks som ett 404 vid det första kommandot:

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

Steg 5: Installera block i ett tema

Skapa blocks.json i roten av temat som ska använda blocken:

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

init --yes skriver ett tomt registries-objekt. Lägg till registret under det namnutrymme du vill skriva i kommandon:

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

Kör init utan --yes i en terminal om du i stället vill besvara samma frågor interaktivt (blockkatalog, registernamn och URL:er).

Kontrollera att registret kan hittas:

Shell
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 matchar en delsträng utan hänsyn till versaler och gemener i namn, titlar och beskrivningar:

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

Förhandsgranska en installation med --dry-run. Beroendet listas först eftersom det installeras först:

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

Installera sedan på riktigt:

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

Båda mapparna finns nu i temats katalog blockstudio, precis som de ligger i repot:

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

Du kan utelämna namnutrymmet när blocket bara finns i ett konfigurerat register och ange flera block på en gång:

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

Blockstudio hittar de nya mapparna precis som andra block i temat.

Uppdatera installerade block

De installerade filerna är kopior. Ingen versionsinformation sparas, och CLI uppdaterar aldrig ett block på egen hand. Lägg till blocket igen för att hämta en nyare version. Utan en terminal, eller i CI, avbryts kommandot om en befintlig mapp hittas:

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

I en terminal frågar CLI i stället innan den skriver över. --dry-run visar mapparna som skulle ersättas, och --yes ersätter dem:

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

Överskrivning ersätter de listade filerna med registrets version, så spara lokala ändringar först och granska resultatet med git diff.

Avinstallera genom att ta bort mappen med dess namn:

Shell
npx blockstudio remove tabs --yes
Kod
Removed tabs

remove tar mappnamnet, inte namespace/block. Det tar inte bort beroenden, så tab-item finns kvar efter att tabs har tagits bort.

Versionshantering med git-referenser

CLI har inget versionsfält och ingen versionsflagga. Vad det hämtar avgörs helt av URL:erna, och på GitHub är ref:en i URL versionen. En konsument som pekar på main får det som main innehåller vid installationstillfället.

Om du vill publicera en fast version måste registry.json vid taggen också hämta från taggen. Ange taggen i baseUrl innan du taggar:

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

Commit:a, tagga och skicka sedan:

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

Ändra sedan baseUrl tillbaka till main och gör en commit, så att branchen fortsätter att leverera aktuella filer. Om du hoppar över det första steget får en konsument som låst sig vid taggen blocklistan från taggen, men hämtar filerna från main.

Konsumenter låser versionen genom att använda taggen i registrets URL:

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

I det här exemplet taggades v1.0.0 innan tabs och tab-item fanns, så registret med låst version erbjuder bara de två ursprungliga blocken:

Shell
npx blockstudio list
Kod
acme (2 blocks)

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

En commit-SHA fungerar också i registrets URL, men en commit kan inte innehålla sin egen SHA i baseUrl. Om du låser versionen med en SHA låses därför blocklistan, medan filerna fortfarande hämtas från den ref som den commitens baseUrl anger. Använd därför taggar för versioner.

Bra att känna till

  • Varje register hämtas först. add läser in alla register i blocks.json innan det löser något, så ett oåtkomligt register gör att kommandot misslyckas även för acme/hero. Ta bort register som du inte längre använder.
  • Tvetydiga namn kräver ett namnutrymme. Om två register båda har hero frågar en terminalsession vilket register som ska användas, --yes väljer det första i blocks.json-ordningen, och en icke-interaktiv körning avslutas med Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Privata repon behöver headers. Använd objektformen för en registerpost med url och headers. Headervärden stöder platshållare för ${VAR}, som läses från miljön, och CLI skickar header-fälten med registerhämtningen och varje filnedladdning. Se GitHub-värdtjänsten för information om tokenkonfigurationen.

Nästa steg