Che cos'è un registry di componenti

Un registry di componenti è un endpoint che espone file sorgente, dipendenze e metadati in un formato che una CLI può installare. Non è un pacchetto npm e non è una pagina di catalogo.

Cosa contiene un record

Un file registry.json dichiara un nome, una lista di items e, per ogni item, un type (registry:ui, registry:block, registry:component), i file, le dipendenze npm e le registryDependencies. Lo schema è documentato da shadcn/ui, progetto MIT, su ui.shadcn.com/docs/registry.

Un record minimo, riga per riga

{
  "name": "hero",
  "type": "registry:block",
  "files": [{ "path": "hero.tsx", "type": "registry:component" }],
  "dependencies": ["lucide-react"],
  "registryDependencies": ["button", "card"]
}

Il record non dichiara una versione e non contiene il codice: indica dove prenderlo. files elenca i percorsi che la CLI scrive nel progetto, dependencies sono pacchetti npm, registryDependencies sono altri record dello stesso registry, risolti prima del tuo. Senza un campo di versione non esiste un percorso di aggiornamento: la copia installata è la tua copia.

Come si installa

npx shadcn@latest add button

Il comando scrive i file nel tuo repository e aggiorna components.json. Con un URL esplicito installi un record remoto, per esempio npx shadcn@latest add https://example.com/r/hero.json; con un namespace, npx shadcn@latest add @eneui/hero. Il codice è tuo: puoi modificarlo dopo l'installazione.

Il 1 novembre 2026 il file data/shadcn_registries.json, copia della directory ufficiale, elenca 525 registry, di cui 517 con health score almeno 50; data/custom_registries.json ne contiene 415 già importati. Il conteggio è una lettura dei due file, non una stima: dice quanti endpoint esistono, non quanti siano ancora mantenuti.

Registry pubblico, registry privato

Un registry pubblico risponde senza autenticazione. Un registry privato richiede un token e spesso un namespace registrato in components.json; senza token l'endpoint risponde 401. Il percorso completo è in 401, 402 e 403 e in token e namespace.

Perché usarlo invece di un pacchetto

Un pacchetto npm centralizza gli aggiornamenti e impone una API. Un registry distribuisce il codice e ti lascia la proprietà: nessun lock-in, ma nessun aggiornamento automatico. Il confronto tra i due modelli è in copy-paste o headless.

Il catalogo EneUI e il suo registry

EneUI indicizza 111.985 componenti e 1.556 blocchi. Ogni record mostra libreria e licenza a monte, per esempio rainbow button di Magic UI. L'endpoint /api/registry/<library>/<name>.json risponde 401 senza token: è un registry privato, non un registry pubblico anonimo. Verifica eseguita il 1 novembre 2026.

La limitazione

Un registry sposta file, non verifica qualità né compatibilità di licenza. Se installi dieci record da dieci registry diversi ottieni dieci stili e dieci versioni di React potenzialmente in conflitto; il registry non te lo impedisce.

La regola di decisione

Scegli un registry quando il componente verrà modificato e versionato insieme al prodotto. Scegli un pacchetto npm quando lo stesso componente serve a tre o più repository e vuoi correggere un bug una volta sola. Nel dubbio apri il record: se dichiara più di cinque registryDependencies, stai installando un albero di file, non un componente.

L'errore da evitare

Installare due record che portano la stessa primitiva da registry diversi: due copie di dialog.tsx, due set di token, due versioni di Radix nel bundle. La CLI scrive i file, non li deduplica. Prima di lanciare il comando confronta le registryDependencies del record con quello che hai già in components/ui.

Dove continuare

Il confronto tra primitive headless è in Radix, Base UI e React Aria. Per capire cosa arriva davvero nel repository leggi registry privati; per la parte visiva parti dai 1.556 blocchi con preview.