shadcn Registry: Fremde Komponenten sicher einbinden

Über eine shadcn Registry kommen Komponenten aus anderen Bibliotheken in ein shadcn/ui-Projekt. Du trägst die Registry in components.json ein, führst npx shadcn@latest add @name/item aus, und die CLI schreibt die Dateien, installiert npm-Pakete und holt die Items, von denen sie abhängen. Das klappt gut, bis ein fremdes Item auf einer Datei landet, die du schon hast, ein erwartetes Token fehlt oder ein nötiger Key nicht gesetzt ist. Dieses Tutorial zeigt die Seite derer, die installieren: was in einem Registry-Item steckt, wie Namespaces und Auth-Header funktionieren, wie du vorab siehst, was eine Installation ändert, was in einem bestehenden Projekt kollidiert und wann sich der Wechsel zu einer CLI lohnt, die Versionen festhält.

Alles Folgende haben wir am 13. Oktober 2026 in einer frischen Next.js-16.4-App getestet, eingerichtet mit shadcn 4.21.4 (Preset radix-nova) und unserer eigenen Registry, Wingo UI Release 1.8.0, mit Version 1.0.3 unserer CLI. Eine eigene shadcn custom registry zu bauen, ist eine andere Aufgabe. Die Registry-Doku von shadcn (opens in a new tab) erklärt sie: Du beschreibst Items in einer registry.json, führst shadcn build aus und hostest das erzeugte JSON.

Was steckt in einem Item einer shadcn Registry?

Eine JSON-Datei pro Item, im Schema registry-item.json, das shadcn veröffentlicht. Unser Button liegt unter /r/button.json. Gekürzt auf die Felder, die bestimmen, was in deinem Projekt landet:

curl -s https://wingo-ui.com/r/button.json \
  | jq '{type, dependencies, registryDependencies, files: [.files[] | {path, type}], cssVars, envVars}'

{
  "type": "registry:ui",
  "dependencies": ["@radix-ui/react-slot@^1.3.3", "motion@^12.43.0"],
  "registryDependencies": [
    "https://wingo-ui.com/r/utils.json",
    "https://wingo-ui.com/r/motion.json",
    "https://wingo-ui.com/r/tones.json",
    "https://wingo-ui.com/r/ui-config.json"
  ],
  "files": [{ "path": "components/ui/button.tsx", "type": "registry:ui" }],
  "cssVars": null,
  "envVars": null
}

• files enthalten den kompletten Quellcode im Feld content, und path bestimmt, wo er landet, nachdem die CLI deine Aliase angewendet hat.
• dependencies sind npm-Pakete, die die CLI installiert.
• registryDependencies sind andere Items, per Name oder URL, rekursiv aufgelöst. Hier entstehen die meisten Überraschungen: Ein Item kann einen ganzen Baum mitbringen.
• Mit cssVars und css kann ein Item CSS-Variablen und Regeln in dein Stylesheet schreiben. Unsere lassen das leer, und das wird später wichtig.
• envVars landen in .env.local oder .env; laut der Schema-Doku (opens in a new tab) werden vorhandene Variablen nicht überschrieben.

Wie füge ich eine shadcn namespaced registry hinzu?

Du trägst sie in das components.json registries-Objekt ein, also unter den Key registries. Der Key jedes Eintrags ist der Namespace, und {name} in der URL wird zum Namen des Items. Eine Registry mit nur kostenlosen Items braucht nicht mehr:

{
  "registries": {
    "@wingo-ui": "https://wingo-ui.com/r/{name}.json"
  }
}

Für private oder kostenpflichtige Items nimmst du die Objektform mit Header. Diese Form steht in unserer Installations-Doku für Pro-Items:

{
  "registries": {
    "@wingo-ui": {
      "url": "https://wingo-ui.com/r/{name}.json",
      "headers": { "Authorization": "Bearer ${WINGO_UI_API_KEY}" }
    }
  }
}

Leg den Key in .env.local ab. Die .gitignore von create-next-app schließt die Datei schon aus:

# .env.local
WINGO_UI_API_KEY=wui_...

Laut der Namespace-Doku von shadcn (opens in a new tab) funktioniert ${VAR} in URLs, Headern und params und wird aus der Umgebung eingesetzt. Zwei Dinge sind uns im Test aufgefallen:

• Keine Variable, keine Installation. Mit der Header-Form und ohne gesetztes WINGO_UI_API_KEY brach npx shadcn@latest view @wingo-ui/button mit der Meldung Registry "@wingo-ui" requires the following environment variables ab, obwohl der Button kostenlos ist. Bleib bei der einfachen URL-Form, bis du einen Key hast.
• Ein kostenpflichtiges Item ohne passenden Key scheitert mit dem Status des Servers. view @wingo-ui/calendar lieferte mit der einfachen URL Failed to fetch from registry (402), weil der Calendar zu Wingo UI Pro gehört.

Wie installiere ich eine Komponente über ihren Namen?

Nenn den Namespace und das Item. Mehrere Items passen in einen Befehl:

npx shadcn@latest add @wingo-ui/calendar
npx shadcn@latest add @wingo-ui/button @wingo-ui/ui-config

Für öffentliche Items reicht auch eine volle URL, ganz ohne Eintrag in components.json: npx shadcn@latest add https://wingo-ui.com/r/button.json. Die Namespace-Form lohnt sich, sobald du mehr als ein Item installierst. Du richtest die Authentifizierung einmal ein, und shadcn search @wingo-ui -q "date" durchsucht die Registry.

Die Demo unten ist der Calendar, den add @wingo-ui/calendar installiert.

Wie prüfe ich, was eine Registry schreibt, bevor ich sie ausführe?

Mit drei Befehlen, der günstigste zuerst. Alle lesen nur die Registry und schreiben nichts.

npx shadcn@latest view @wingo-ui/button                    # Metadaten, Abhängigkeiten, Quellcode jeder Datei
npx shadcn@latest add @wingo-ui/button --dry-run           # aufgelöste Dateiliste: anlegen oder überschreiben
npx shadcn@latest add @wingo-ui/button --diff lib/utils.ts # eine Datei: deine gegen ihre

Am wichtigsten ist --dry-run, denn es löst den ganzen Abhängigkeitsbaum auf. In unserem Projekt, das schon Button und Card von shadcn/ui hatte, kam Folgendes heraus:

┌ shadcn add @wingo-ui/button (dry run)
│
├ Files (6) +4 new, ~2 overwrite
│ ~ lib/utils.ts              overwrite
│ + hooks/use-media-query.ts  create
│ + lib/tones.ts              create
│ + lib/ui-config.tsx         create
│ + lib/motion.ts             create
│ ~ components/ui/button.tsx  overwrite
│
├ Dependencies (4)
│ + clsx@^2.1.1
│ + tailwind-merge@^3.7.0
│ + motion@^12.43.0
│ + @radix-ui/react-slot@^1.3.3
│
⚠ 2 files will be overwritten.

Ein Button, sechs Dateien, zwei davon deine. --view <path> gibt den Inhalt einer Datei aus, und --diff <path> vergleicht ihn mit deiner Version. Lies jede Zeile mit ~, bevor du installierst, und committe vorher, damit git diff alles rückgängig machen kann.

Was kollidiert in einem bestehenden shadcn/ui-Projekt?

Vier Dinge, in der Reihenfolge, in der du auf sie stößt.

lib/utils.ts

Die meisten unserer Items hängen von einem Item utils ab, das lib/utils.ts schreibt. Die CLI fragt deshalb, ob sie die vorhandene utils.ts überschreiben soll. shadcn 4.21.4 hat unser Projekt mit einer einzeiligen Datei eingerichtet, export { cn } from "cn"; unsere ist die ältere Variante mit clsx und tailwind-merge. Antworte mit Nein. Unsere Komponenten importieren nur cn aus @/lib/utils, und der Button von Wingo UI bestand den Type-Check gegen die einzeilige Datei von shadcn.

Gleichnamige Dateien

Stand 4.21.4 liefert shadcn/ui 62 ui-Items aus, und fremde Bibliotheken nutzen dieselben Namen, weil sie ebenfalls nach components/ui installieren. Unser Button und der von shadcn teilen sich button.tsx, mit unterschiedlichen APIs: Unserer hat die variant-Werte solid, soft, outline, ghost und link und nutzt tone="danger", wo shadcn variant="destructive" verwendet.

Durch Abhängigkeiten wird das Problem größer, als es aussieht. Der Calendar hängt von unserem Button ab, also überschreibt seine Installation auch deinen Button. Antwortest du mit Nein, bleibt ein Calendar übrig, der variant="soft" und radius="full" an einen Button übergibt, der beides nicht kennt. Die Data Table löst sich in 47 Items auf, sich selbst mitgezählt; 28 davon sind Dateien in components/ui, und 20 davon heißen genauso wie eine Komponente von shadcn/ui, von avatar.tsx bis tooltip.tsx.

Die Lösung ist ein Ordner pro Bibliothek. Zeig mit dem ui-Alias der zweiten Bibliothek auf einen eigenen Ordner, dann bleibt components/ui bei shadcn. Unser Setup für Claude Code mit shadcn zeigt dieses Layout mit components/wingo.

CSS-Variablen

Beide Bibliotheken definieren --background, --accent, --radius und andere gemeinsame Namen, mit unterschiedlicher Bedeutung:

• --accent ist in shadcn/ui ein helles Grau (oklch(0.97 0 0) in unserem radix-nova-Projekt) für hervorgehobene Einträge. Unser Stylesheet definiert es als orangen Farbton, und unsere Komponenten nutzen bg-accent nie.
• --radius ist in diesem Projekt 0.625rem. Unserer ist 0.375rem, für älteren Code beibehalten und gepaart mit --radius-md: calc(var(--radius) - 2px), wodurch rounded-md 4px ergibt.

Kopierst du unsere Tokens über deine, werden die Hervorhebungen von shadcn/ui orange und seine Ecken schrumpfen. Das umgekehrte Problem tritt mit der shadcn CLI auf: Unsere Items setzen cssVars auf null, also fügt nichts die Tokens hinzu, die sie nutzen. Klassen wie shadow-raised und z-modal laufen dann ins Leere. Der sichere Merge ist npx wingo-ui@latest init. In unserem Projekt hat er 43 Variablen, 17 Dark-Werte und 43 @theme-Mappings ergänzt und keine bestehende Zeile geändert, also behielten --accent und --radius die Werte von shadcn. Unsere Komponenten nutzen feste Eckenradien (ein mittlerer Button ist rounded-[10px]), dein --radius ändert sie also nicht.

Base-UI-Styles und asChild

shadcn-Styles mit dem Namen base-* nutzen Base UI, und die CLI schreibt asChild beim Installieren in den render-Prop von Base UI um. Wir haben "style": "base-nova" gesetzt und add @wingo-ui/dialog --dry-run --view components/ui/dialog.tsx ausgeführt: Aus <DialogClose asChild> wurde <DialogClose render={<Button ... />}>, aber unser Dialog importiert weiterhin Radix, und Radix kennt keinen render-Prop. In einem Base-UI-Projekt installierst du deshalb mit unserer CLI, die Dateien so schreibt, wie sie veröffentlicht sind.

Wann lohnt sich der Wechsel von der shadcn CLI zur Wingo UI CLI?

Wenn du Updates willst. Die shadcn CLI hält nichts darüber fest, was sie installiert hat. Ein späteres Release erreicht deine Dateien also nur über add --overwrite, und das verwirft deine Änderungen. Unsere CLI schreibt wingo-ui.json mit der Version jedes Items und legt die installierte Kopie in .wingo-ui/base ab. Erst das macht den 3-Way-Merge von update möglich. Um für die Items, die du von uns installiert hast, von der CLI von shadcn/ui auf unsere umzusteigen, installierst du nichts neu:

npx wingo-ui@latest init         # wingo-ui.json, fehlende Tokens, behält lib/utils.ts
npx wingo-ui@latest add button   # festhalten, was du schon hast
npx wingo-ui@latest outdated

init übernimmt components.json nicht. Es liest daraus ein einziges Feld, tailwind.css, um dein Stylesheet zu finden, nimmt den Alias @/* aus tsconfig.json und schreibt seine eigenen Ordner in wingo-ui.json. Ändere dort also aliases.ui, wenn unsere Dateien außerhalb von components/ui liegen. In unserem Test fand es das export { cn } from "cn" von shadcn und behielt es.

add vergleicht danach jede Datei mit dem aktuellen Release. In unserem Projekt, in das Button und Helfer über shadcn add @wingo-ui/button gekommen waren, meldeten alle fünf Dateien identical und wurden mit 1.0.0 erfasst, und outdated zeigte sie als aktuell an.

Eine Datei, die du bearbeitet hast, meldet stattdessen conflict und wird nicht erfasst. Sichere deine Kopie, hol dir unsere mit --overwrite und spiel deine danach zurück:

cp components/ui/button.tsx /tmp/button.mine.tsx
npx wingo-ui@latest add button --overwrite
cp /tmp/button.mine.tsx components/ui/button.tsx
npx wingo-ui@latest diff button   # sollte nur deine Änderungen zeigen

Das ist exakt, wenn deine Kopie aus dem aktuellen Release stammt. Ist sie älter, zeigt diff auch die Upstream-Änderungen, die du nie bekommen hast, als wären es deine. Prüf sie dort.

Wenn du schon dabei bist, lager geänderte Standardwerte aus der Datei aus. Wir hatten in button.tsx radius = "md" auf "full" geändert; dasselbe Ergebnis als Default im UIProvider lässt die Datei unberührt, und das nächste Update hat nichts zu mergen:

// app/providers.tsx
"use client";

import type { ReactNode } from "react";
import { UIProvider } from "@/lib/ui-config";

export function Providers({ children }: { children: ReactNode }) {
  return <UIProvider defaults={{ button: { radius: "full" } }}>{children}</UIProvider>;
}

Wie der Merge selbst funktioniert, samt einem Git-Skript, das dasselbe für unveränderte Dateien von shadcn/ui erledigt, steht in unserem Guide zum Aktualisieren von shadcn-Komponenten, ohne Änderungen zu verlieren. Die Befehle findest du auf der Doku-Seite zu Updates.

Wo fange ich an?

Trag die Registry mit der einfachen URL ein, führ npx shadcn@latest add @wingo-ui/button --dry-run in deinem Projekt aus und lies die Liste, die dabei herauskommt. Taucht button.tsx als Überschreibung auf, wähl einen Ordner für die zweite Bibliothek, bevor du irgendetwas installierst. Calendar und Data Table gehören zu Wingo UI Pro, siehe Preisseite; Button und UIProvider sind kostenlos. Wie sich die beiden Bibliotheken über die Registry hinaus unterscheiden, liest du in Wingo UI vs shadcn/ui, und weitere Deep Dives findest du unter Komponenten-Guides.

Häufige Fragen

Was ist eine shadcn Registry?

Ein Server, der Komponenten als JSON-Dateien im registry-item-Format von shadcn veröffentlicht: den Quellcode jeder Datei, die nötigen npm-Pakete und die anderen Items, von denen sie abhängt. Die shadcn CLI liest diese Dateien und schreibt den Quellcode in dein Projekt.

Wie füge ich eine fremde Registry zu components.json hinzu?

Leg unter registries einen Eintrag an, etwa "@wingo-ui": "https://wingo-ui.com/r/{name}.json (opens in a new tab)". Für private oder kostenpflichtige Items nimmst du die Objektform mit url und headers und schreibst den Key als ${VAR}, damit die CLI ihn aus der Umgebung oder aus .env.local liest.

Warum bricht die shadcn CLI mit einem Fehler zu einer fehlenden Umgebungsvariable ab?

Eine Registry in components.json nutzt ${VAR} in ihrer URL oder ihren Headern, und die Variable ist nicht gesetzt. Setz sie in .env.local oder in deiner Shell, oder nutz die einfache URL-Form, solange du nur kostenlose Items installierst.

Sollte eine fremde Registry meine lib/utils.ts überschreiben?

Meistens nicht. Wenn deine Datei schon cn exportiert, funktionieren Komponenten weiter, die cn aus @/lib/utils importieren. In unserem Test bestand der Button von Wingo UI den Type-Check gegen die einzeilige lib/utils.ts von shadcn, die cn aus dem Paket cn re-exportiert.

Kann ich später von der shadcn CLI auf die CLI einer Bibliothek wechseln?

Ja. Bei Wingo UI führst du im selben Projekt npx wingo-ui@latest init aus und danach npx wingo-ui@latest add für die Items, die du installiert hast. Dateien, die dem aktuellen Release entsprechen, werden als installiert erfasst, sodass spätere Updates in sie gemergt werden können.