Gå til indhold

Udgivelse af et blokregister på GitHub

Når du har bygget nogle gode blokke, vil du også bruge dem i det næste projekt. Manuel kopiering af mapper mellem temaer fungerer, indtil kopierne afviger fra hinanden, og ingen kan huske, hvilket tema der har den rettede version. Det er meget omstændeligt at pakke hver blok ind i en pakke med sit eget buildsystem, når det blot drejer sig om en mappe med et block.json og en skabelon.

Et blokregister løser det mellemtrin. Det består af en registry.json-fil og et sæt blokmapper, der serveres via almindelig HTTP. Brugere kører en CLI-kommando, blokkenes kildefiler kopieres ind i deres tema, og derefter ejer de selv kopien. Et GitHub-repository er nok til at hoste et register, fordi GitHub serverer alle filer i et offentligt repository via en rå URL.

Denne vejledning bygger et register med navnet acme og fire blokke, udgiver det fra repositoriet acme/acme-blocks, installerer blokke derfra i et tema og fastlåser en udgivelse med et git-tag.

Pakken blockstudio på npm er version 0.0.1. Den udgivelse er en pladsholder: dens eneste kommando, add, udskriver Adding block: <name> og afsluttes uden at hente noget. Kommandoerne og outputtet i denne vejledning kommer fra registret CLI i repositoriet Blockstudio (packages/registry), som er det CLI, der beskrives i registerdokumentationen.

Sådan passer delene sammen

Der er to filer, du skal kende:

  • registry.json udgives af blokforfatteren. Den angiver blokkene, de filer hver blok består af, og en baseUrl, hvorfra de kan hentes.
  • blocks.json ligger i brugerens tema eller plugin. Den angiver, hvilke registre der skal bruges, og hvilken mappe blokkene installeres i.

Når du installerer en blok, henter CLI alle registre i blocks.json, finder blokken, løser dens afhængigheder, downloader hver angivet fil fra {baseUrl}/{block}/{file} og skriver den til {directory}/{block}/{file}. Intet transformeres, så filerne på disken er nøjagtig de samme som i repositoriet.

Trin 1: Strukturér repositoriet

Opret et repository med en registry.json i roden og én mappe pr. blok under 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

Mappenavnet er blokkens navn i registret og bliver også mappenavnet i brugerens tema. Sørg for, at det er identisk med den anden del af bloknavnet i block.json (acme/hero ligger i hero/), så den installerede mappe er nem at genkende.

Trin 2: Skriv blokkene

Hver mappe er en almindelig Blockstudio-blok. Heroblocken har ét felt:

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ølger samme mønster og tilføjer en style.scss. tabs gengiver <InnerBlocks allowedBlocks='["acme/tab-item"]' />, og tab-item erklærer "parent": ["acme/tabs"], så tabs ikke er nyttig uden tab-item. Registret angiver denne relation i næste trin.

Der er intet særligt ved registret i disse blokke. CLI kopierer mapper, så en blok, der er bygget med @wordpress/create-block eller registreret med almindelig PHP, kan udgives på samme måde.

Trin 3: Skriv registry.json

registry.json angiver alle blokke og alle de filer, som CLI skal downloade:

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

Nogle få regler afgør, om denne fil fungerer:

  • files er en eksplicit liste. CLI downloader præcis disse stier og intet andet. Der bruges ingen globbing, så et nyt aktiv kommer først med, når du tilføjer det her. Stier kan indeholde undermapper, som oprettes under installationen.
  • baseUrl skal være en absolut URL. CLI validerer den som en URL og afviser relative værdier. Block-filer hentes altid fra baseUrl, aldrig fra en placering relativ til der, hvor registry.json blev indlæst.
  • dependencies angiver blocks ved navn i samme registry. Når du tilføjer tabs, installeres tab-item først. Manglende og cirkulære afhængigheder stopper installationen med en fejl.
  • name er påkrævet, men vises ikke. Kommandoer og output bruger den nøgle, som forbrugeren giver registry’en i blocks.json; den behøver ikke at være den samme.
  • type er kun til information. Den accepterer blockstudio, create-block eller wordpress og ændrer ikke, hvad CLI gør.

CLI validerer hele filen ved hver hentning og rapporterer hvert felt med fejl, så en slåfejl opdages, før nogen fil downloades. Linjen $schema giver dig de samme kontroller i din editor.

Trin 4: Udgiv via raw-URL’er

Commit og push repository’et til GitHub. Alle filer i et offentligt repository bliver derefter tilgængelige på:

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

<ref> er en branch, et tag eller en commit-SHA. For dette registry er der to relevante URL’er:

  • Registry-URL, som forbrugerne konfigurerer: 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 hentes index.php for hero fra https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. Den rå vært returnerer filindhold i stedet for siden GitHub HTML, som CLI har brug for. En forkert ejer, et forkert repository eller en forkert ref viser sig som en 404 ved den første kommando:

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

Trin 5: Installér blocks i et theme

Opret blocks.json i roden af det theme, der skal bruge registry’et:

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

init --yes skriver et tomt registries-objekt. Tilføj registry’et under det namespace, du vil skrive i kommandoer:

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 uden --yes i en terminal for at besvare de samme spørgsmål interaktivt (block-mappe, registry-navne og URL’er).

Kontrollér, at registry’et kan findes:

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 søger efter en delstreng uden forskel på store og små bogstaver i navne, titler og beskrivelser:

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.

Forhåndsvis en installation med --dry-run. Afhængigheden vises først, fordi den installeres først:

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

Installér derefter for alvor:

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

Begge mapper ligger nu i theme’ets blockstudio-mappe, præcis som i repository’et:

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

Du kan udelade namespace, når kun ét konfigureret registry har block’en, og angive flere blocks på én gang:

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

Blockstudio finder de nye mapper på samme måde som alle andre blocks i theme’et.

Opdatering af installerede blocks

De installerede filer er en kopi. Der registreres ikke, hvilken version du installerede, og CLI opdaterer aldrig en block af sig selv. Hent en nyere version ved at tilføje block’en igen. Uden en terminal eller i CI stopper kommandoen, hvis mappen allerede findes:

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

I en terminal spørger CLI i stedet, før den overskriver. --dry-run rapporterer, hvilke mapper den ville erstatte, og --yes erstatter dem:

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

Overskrivning erstatter de angivne filer med registry’ets version, så commit først lokale ændringer, og gennemgå resultatet med git diff.

Afinstallér ved at fjerne mappen ved navn:

Shell
npx blockstudio remove tabs --yes
Kode
Removed tabs

remove tager mappenavnet, ikke namespace/block. Afhængigheder fjernes ikke, så tab-item forbliver installeret, når tabs fjernes.

Versionsstyring med git-referencer

CLI har hverken et versionsfelt eller et versionsflag. Det, der hentes, afgøres udelukkende af URL’erne, og på GitHub er ref’en i URL versionen. En forbruger, der peger på main, får det, som main indeholder på installationstidspunktet.

Hvis du vil udgive en fastlåst version, skal registry.json ved tagget også hente fra tagget. Indstil baseUrl til tagget, før du opretter tagget:

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

Commit, opret et tag, og push derefter:

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

Bagefter skal du sætte baseUrl tilbage til main og committe, så branchen fortsat leverer aktuelle filer. Hvis du springer første trin over, får en forbruger, der er fastlåst til tagget, block-listen fra tagget, men filerne hentes fra main.

Forbrugere fastlåser versionen ved at bruge tagget i deres registry-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 dette eksempel blev v1.0.0 tagget, før tabs og tab-item fandtes, så det fastlåste registry tilbyder kun de to oprindelige blocks:

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

En commit-SHA fungerer også i registry-URL, men en commit kan ikke indeholde sin egen SHA i baseUrl. Fastlåsning med SHA fastlåser derfor block-listen, mens filerne stadig hentes fra den ref, som commit’ens baseUrl angiver. Brug derfor tags til udgivelser.

Vær opmærksom på følgende

  • Hvert registry hentes først. add indlæser alle registries i blocks.json, før den løser noget, så ét utilgængeligt registry får kommandoen til at fejle, selv for acme/hero. Fjern registries, du ikke længere bruger.
  • Tvetydige navne kræver et namespace. Hvis to registries begge har hero, spørger en terminalsession, hvilket der skal bruges. --yes vælger det første i rækkefølgen i blocks.json, og en ikke-interaktiv kørsel afsluttes med Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Private repositories kræver headers. Brug objektformen for et registry-element med url og headers. Headerværdier understøtter ${VAR}-pladsholdere, som læses fra miljøet, og CLI sender headerne med ved hentning af registry’et og hver fil. Se GitHub-hosting for opsætning af token.

Næste trin