Die shadcn Registry, erklärt

Eine shadcn Registry ist JSON, das über HTTP bereitgestellt wird. Das ist die gesamte Idee. Es gibt kein Paket zum Publizieren, keine Runtime, keinen Dienst, für den man sich registrieren muss: Man hostet Dateien unter URLs, und die shadcn CLI ruft eine davon ab, liest die Deklarationen und schreibt das Ergebnis in das Zielprojekt.

Das ist der Unterschied zu einer Komponentenbibliothek. Eine Bibliothek ist eine Abhängigkeit – man installiert sie, importiert daraus, und der Code lebt hinter einer Versionsnummer in node_modules. Eine Registry liefert Quellcode. Nach shadcn add gehören die Dateien einem selbst: sie liegen im eigenen Repo, erscheinen im Diff und sind ohne Fork editierbar. Der Preis dafür ist der übliche – man übernimmt die Wartung und verliert automatische Updates – und genau auf diesem Kompromiss basiert der gesamte shadcn-Ansatz.

Man kann ein einzelnes Element publizieren, ohne jemals einen Index zu erstellen. Das ist der schnellste Weg, eine Registry sinnvoll zu nutzen, und darauf baut der Rest dieses Guides auf – dennoch lohnt es sich, die Felder vorab zu kennen.

• `name` — der Bezeichner, der in Installationsbefehlen und in registryDependencies verwendet wird.
• `type` — die Art des Elements: registry:ui für eine Komponente, registry:block für einen zusammengesetzten Block aus mehreren Dateien, registry:theme für einen Satz an Design-Tokens, registry:style für einen kompletten Basis-Style sowie Varianten für Hooks, Libs, Pages und Files.
• `files` — der zu schreibende Quellcode, jeweils mit eigenem type und optionalem target-Pfad.
• `dependencies` — npm-Pakete, die das Element benötigt und die automatisch installiert werden.
• `registryDependencies` — andere Registry-Elemente, die dieses Element benötigt, referenziert per Name oder URL. Die CLI löst diese auf, weshalb sich die Installationsreihenfolge automatisch sortiert.
• `cssVars` — CSS-Custom-Properties, aufgeteilt in theme, light und dark.
• `css` — beliebige CSS-Regeln für alles, was nicht über Variablen ausgedrückt werden kann.
• `font` — benötigte Schriftarten, damit die Typografie kein separater manueller Schritt ist.
• `categories`, `docs`, `meta` — Metadaten für Explorer, Anweisungen nach der Installation und eigene benutzerdefinierte Daten.

Die drei am häufigsten übersehenen Felder sind cssVars, css und font, da fast jedes Tutorial eine Komponente demonstriert. Genau diese drei machen aus einer Registry einen Mechanismus zur Distribution von Designsystemen statt nur zur Distribution von Komponenten.

Hier ist ein reales Beispiel, das aktuell live ist — das Item hinter dem kostenlosen Ambient Sage Kit, gekürzt zur besseren Übersicht. Es enthält keine einzige Komponente:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "ambient-sage",
  "type": "registry:theme",
  "title": "Ambient Sage",
  "description": "A warm-sage neutral-surface kit with a single vivid yellow accent.",
  "categories": ["minimal", "warm-neutral", "flat", "calm", "yellow-accent"],
  "cssVars": {
    "theme": {
      "font-heading": "'Plus Jakarta Sans', sans-serif",
      "font-mono": "'JetBrains Mono', monospace",
      "radius-button": "0.75rem",
      "radius-card": "1.25rem",
      "shadow-sm": "none",
      "duration": "180ms",
      "ease": "cubic-bezier(0.4,0,0.2,1)"
    },
    "light": {
      "background": "72 19% 95%",
      "foreground": "84 10% 10%",
      "card": "70 11% 89%",
      "primary": "54 98% 66%"
    },
    "dark": {
      "background": "84 10% 10%",
      "foreground": "68 13% 88%",
      "card": "80 9% 14%"
    }
  },
  "font": { "heading": "Plus Jakarta Sans", "mono": "JetBrains Mono" },
  "docs": "Use the semantic tokens; do not add a second accent."
}

Drei Dinge sind bemerkenswert: cssVars.theme enthält den nicht farblichen Teil eines Designsystems — Radien, Schatten, Motion-Timing, Schriftarten — genau dort, wo die meisten „Theme-Generatoren“ aufhören und das Design verloren geht. light und dark sind separate Objekte und keine einzelne Palette mit einer Invertierung. Und docs enthält eine schriftliche Anweisung, die das CLI nach der Installation ausgibt und die ein Coding-Agent lesen kann.

Die Installation erfolgt mit einem einzigen Befehl und übermalt ein bestehendes Projekt, anstatt es nur zu ergänzen: Jede Komponente, die bereits auf bg-primary oder text-muted-foreground verweist, übernimmt die neuen Werte, ohne bearbeitet werden zu müssen.

npx shadcn add https://identityforge.io/r/ambient-sage.json

1. 1

   Eine Item-Datei schreiben

   Beginnen Sie mit einer einzigen registry-item.json. Sie benötigen keine registry.json, keinen Build-Schritt und kein Monorepo, um nützlich zu sein — ein Index wird erst wichtig, wenn Sie mehrere Items haben und einen Namespace wünschen.

2. 2

   Unter einer stabilen URL bereitstellen

   Jeder statische Host ist geeignet. Entscheidend ist, dass die URL stabil bleibt: Sie ist der Installationsbefehl und landet somit in READMEs, Prompts und Agent-Konfigurationen.

   Copy

   https://identityforge.io/r/<slug>.json

3. 3

   Richtigen Content-Type und CORS setzen

   Stellen Sie application/json bereit. Falls das Item im Browser abgerufen werden soll — durch einen Registry-Explorer oder ein Preview-Tool —, senden Sie zusätzlich permissive CORS-Header. Dies ist der häufigste Grund, warum ein korrekt aussehendes Item nicht installiert werden kann.

4. 4

   Mit dem echten CLI testen

   Installieren Sie das Item in einem Testprojekt, bevor Sie die URL veröffentlichen. Ein Schema-Fehler fällt hier innerhalb von Sekunden auf; in einem Bug-Report erst nach Wochen.

   Copy

   npx shadcn add https://example.com/r/thing.json

Eine einfache URL reicht für ein einzelnes Item aus. Sobald Sie mehrere veröffentlichen, ist ein Namespace vorteilhafter: Konfigurieren Sie die Registry einmal in der components.json und installieren Sie über Kurznamen, wobei mehrere Registries nebeneinander existieren können.

Private Registries werden unterstützt, und das CLI akzeptiert vier Authentifizierungsformen: einen Bearer-Token (OAuth 2.0), einen API-Key, Basic-Authentication und einen Query-Parameter. Die Wahl hängt von der Hosting-Entscheidung ab, nicht von shadcn/ui.

registryDependencies ermöglicht es einem Item, von anderen Items abzuhängen, auch über Registry-Grenzen hinweg. Das CLI löst den Graphen auf und installiert in Abhängigkeitsreihenfolge. So erhält ein Block, der einen Button benötigt, zuerst den Button, unabhängig davon, ob dieser explizit angefordert wurde.

Ein bekanntes Fehlerbild ist der Zyklus: zwei Items, die sich gegenseitig als Abhängigkeit deklarieren. Nichts wird aufgelöst, und die Fehlermeldung weist auf den Auflösungsschritt statt auf Ihr JSON hin. Wenn eine Installation bei einem korrekt aussehenden Item hängen bleibt oder fehlschlägt, zeichnen Sie die Abhängigkeitspfeile auf Papier, bevor Sie weitere Fehleranalysen durchführen.

Dies ist die am häufigsten gestellte und am seltensten beantwortete Frage zu Registries, und es gibt drei echte Antworten: shadcn/ui pflegt einen Open-Source-Registry-Index mit Registries, die sofort verfügbar sind. registry.directory ist ein unabhängiger Explorer, mit dem Items vor der Installation durchsucht und in der Vorschau angezeigt werden können. Und eine wachsende Zahl einzelner Projekte — einschließlich dieser Seite — veröffentlichen eine stabile Item-URL und dokumentieren diese einfach.

Die dritte Kategorie wird leicht übersehen, ist aber die erste, die man prüfen sollte: Wenn ein Projekt, das Ihnen gefällt, ein Theme oder einen Komponentensatz besitzt, den Sie möchten, suchen Sie nach einem /r/-Pfad, bevor Sie annehmen, dass Sie CSS manuell kopieren müssen.

Ein Coding-Agent, dem drei Markenfarben gegeben werden, hat drei Werte und etwa fünfundzwanzig undefinierte: Hover- und Active-Zustände, gedämpfter Text, Rahmen, Ringe, destruktive Elemente, Chart-Serien und all das noch einmal im Dark Mode. Der Agent füllt diese kompetent, aber jedes Mal anders aus — genau das ist der Drift, den ein Designsystem verhindern soll.

Ein Registry-Item schließt diese Lücke mit einem einzigen Befehl und ist in einer Weise portabel, wie es sonst nichts in diesem Bereich ist: v0 akzeptiert eine Registry als Designsystem-Quelle, Bolt kann eine über das In-Browser-Terminal installieren, und Cursor oder Claude Code können denselben Befehl in Ihrem Repo ausführen. Eine URL, vier Tools, keine toolspezifische Integration. Der schriftliche Teil — was niemals zu tun ist, welche Variante eine destruktive Aktion erhält — gehört daneben in eine DESIGN.md, denn cssVars beantwortet die Frage *welche Farbe*, aber nur Prosa beantwortet die Frage *was niemals*.