Zum Inhalt springen

GitHub

GitHub ist die einfachste Möglichkeit, eine Registry zu hosten. Lade deine Blöcke in ein Repository hoch und verwende die Raw-Content-URLs von GitHub.

Einrichtung

Erstelle ein Repository mit folgender Struktur:

Code
acme-blocks/
  registry.json
  blocks/
    hero/
      block.json
      index.php
    card/
      block.json
      index.php
      style.scss

registry.json

Setze baseUrl auf die Raw-GitHub-URL für dein Verzeichnis blocks/:

JSON
{
  "name": "acme",
  "description": "Acme Corp block library.",
  "baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
  "blocks": [
    {
      "name": "hero",
      "title": "Hero",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    },
    {
      "name": "card",
      "title": "Card",
      "category": "components",
      "type": "blockstudio",
      "files": ["block.json", "index.php", "style.scss"]
    }
  ]
}

baseUrl verwendet raw.githubusercontent.com, damit CLI den Dateiinhalt im Raw-Format und nicht die GitHub-HTML-Seite erhält.

Konfiguration für Nutzer

Nutzer fügen deine Registry zu ihrer blocks.json hinzu:

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

Danach:

Shell
npx blockstudio add acme/hero

Auf eine Version festlegen

Um eine bestimmte Version festzulegen, verwende statt main ein Tag oder eine Commit-SHA:

JSON
{
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

So wirken sich inkompatible Änderungen nicht auf bestehende Projekte aus, sofern registry.json in diesem Tag ebenfalls das Tag in seiner baseUrl verwendet. CLI lädt Blockdateien von baseUrl herunter. Zeigt die baseUrl eines getaggten registry.json weiterhin auf main, werden die Dateien von main installiert. Dasselbe gilt für eine Commit-SHA: Sie legt die Blockliste fest, während die Dateien aus dem Ref stammen, das die baseUrl dieses Commits angibt.

GitHub Pages

Du kannst eine Registry auch über GitHub Pages bereitstellen, wenn du eine übersichtlichere URL bevorzugst:

  1. Aktiviere GitHub Pages für das Repository
  2. Setze baseUrl auf deine Pages-URL: https://acme.github.io/acme-blocks/blocks
  3. Die registry.json ist unter https://acme.github.io/acme-blocks/registry.json erreichbar

Private Repositories

Verwende für private Repos das Registry-Objektformat mit einem persönlichen GitHub-Zugriffstoken:

JSON
{
  "registries": {
    "private": {
      "url": "https://raw.githubusercontent.com/acme/private-blocks/main/registry.json",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

Lege das Token in deiner Umgebung fest:

Shell
export GITHUB_TOKEN=ghp_abc123
npx blockstudio add private/hero

Für den Zugriff auf Inhalte privater Repositories über raw.githubusercontent.com benötigt das Token den Bereich repo (oder contents:read bei fein abgestuften Tokens).