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.jsonudgives af blokforfatteren. Den angiver blokkene, de filer hver blok består af, og enbaseUrl, hvorfra de kan hentes.blocks.jsonligger 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/:
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:
{
"$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 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:
{
"$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:
fileser 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.baseUrlskal være en absolut URL. CLI validerer den som en URL og afviser relative værdier. Block-filer hentes altid frabaseUrl, aldrig fra en placering relativ til der, hvorregistry.jsonblev indlæst.dependenciesangiver blocks ved navn i samme registry. Når du tilføjertabs, installerestab-itemførst. Manglende og cirkulære afhængigheder stopper installationen med en fejl.nameer påkrævet, men vises ikke. Kommandoer og output bruger den nøgle, som forbrugeren giver registry’en iblocks.json; den behøver ikke at være den samme.typeer kun til information. Den acceptererblockstudio,create-blockellerwordpressog æ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å:
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 baseUrliregistry.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:
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:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yes skriver et tomt registries-objekt. Tilføj registry’et under det namespace, du vil skrive i kommandoer:
{
"$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:
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 søger efter en delstreng uden forskel på store og små bogstaver i navne, titler og beskrivelser:
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.
Forhåndsvis en installation med --dry-run. Afhængigheden vises først, fordi den installeres først:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Installér derefter for alvor:
npx blockstudio add acme/tabs
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:
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:
npx blockstudio add hero card
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:
npx blockstudio add tab-item
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:
npx blockstudio add acme/tab-item --dry-run
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:
npx blockstudio remove tabs --yes
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:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Commit, opret et tag, og push derefter:
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:
{
"$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:
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".
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.
addindlæser alle registries iblocks.json, før den løser noget, så ét utilgængeligt registry får kommandoen til at fejle, selv foracme/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.--yesvælger det første i rækkefølgen iblocks.json, og en ikke-interaktiv kørsel afsluttes medBlock "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
urlogheaders. 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
- Registry-oversigt: hvad registry’et er, og hvordan CLI fungerer
- registry.json: alle manifestets felter
- blocks.json: forbrugerkonfiguration, godkendelse og konfigurationsopdagelse
- tilføj: namespace-opløsning, afhængigheder og overskrivningsadfærd
- GitHub-hosting: GitHub Pages og private repositories
- Tilpasset server: levering af et registry fra din egen infrastruktur