Sviluppo web

Come usare la CLI di shadcn/ui, comando per comando

Dopo `init` la CLI ha altri cinque comandi utili: `view`, `search`, `add --diff`, `build` per un registry tuo e `migrate` per i token.

In sintesi

  • `view` e `search` leggono un registry senza scrivere file nel progetto.
  • `add --dry-run` elenca i file, `add --diff` mostra le righe: il secondo è l'unico che vede un conflitto.
  • `build` trasforma il tuo `registry.json` in JSON installabili con `add`.

Dopo l'installazione la CLI di shadcn/ui si usa per quattro comandi: view legge il sorgente, add --diff mostra le righe che cambiano e build genera un registry dal tuo registry.json. La versione misurata è shadcn 4.23.0.

Vedere un componente prima di installarlo

npx shadcn@latest search @shadcn -q "data table"
npx shadcn@latest view button card dialog

search interroga un registry e stampa nome e descrizione; view stampa il codice dei file. Nessuno dei due scrive nel progetto: sono i comandi da usare quando non ricordi cosa fa un blocco.

Il diff prima della scrittura

npx shadcn@latest add card --dry-run
npx shadcn@latest add card --diff components/ui/card.tsx

--dry-run elenca i file che il comando scriverebbe; --diff mostra le righe che cambierebbero in un file già modificato. Se il componente è tuo da mesi, il diff è l'unico controllo che vede il conflitto prima della sovrascrittura.

La configurazione come dato

npx shadcn@latest info --json
npx shadcn@latest info --json > shadcn-info.json

info stampa alias, percorso del CSS, base color e stile. Con --json l'output entra in uno script: in CI puoi verificare che il percorso del CSS non sia cambiato dopo un merge.

Pubblicare un registry tuo

npx shadcn@latest build
npx shadcn@latest build registry.json --output ./public/r

build legge registry.json e scrive i JSON in public/r: da lì i tuoi componenti si installano con add e un URL. La licenza resta la tua, perché il registry è un formato di distribuzione, non un fork.

Migrazioni e preset

npx shadcn@latest migrate --list
npx shadcn@latest migrate cn
npx shadcn@latest preset decode a2r6bw

migrate --list elenca le migrazioni disponibili: cn sostituisce clsx e tailwind-merge, base-color cambia i token del tema. preset decode spiega cosa contiene un codice preset prima che tu lo applichi.

Limite dichiarato

La CLI non risale l'albero delle cartelle: cerca components.json nella cartella corrente o in quella passata con -c. In un monorepo il comando lanciato dalla radice fallisce anche quando il file esiste due livelli sotto.

Dove continuare

Il catalogo EneUI parte dalla libreria shadcn, con 61 componenti, e da record come la sidebar; le 1.556 anteprime di blocchi mostrano il risultato composto. Il primo passo resta installare shadcn/ui, il secondo è aggiungere un blocco. Per scegliere il tema leggi temi gratis o premium; per i registry privati, token e namespace.

Domande frequenti

A cosa serve il comando view?

Mostra il codice di un componente senza installarlo. Serve a controllare dipendenze e stile prima di scrivere file nel progetto, e a confrontare due registry.

Che differenza c'è fra --dry-run e --diff?

dry-run elenca i file che verrebbero scritti, diff mostra le righe che cambierebbero in un file specifico. Il primo è una lista, il secondo un confronto.

Posso installare da un registry privato?

Sì, add accetta un URL al posto del nome del componente. Se il registry richiede autenticazione, il token si configura nella voce registries di components.json, non sulla riga di comando.

Perché build non trova registry.json?

Perché il comando legge ./registry.json rispetto alla cartella corrente. Passa il percorso come argomento oppure sposta il file nella radice da cui lanci il comando.

La CLI funziona senza components.json?

Per view, search e migrate cn sì. Per add e info no, perché senza components.json non conosce alias, percorso del CSS e componente di base.