Come installare shadcn/ui in un progetto esistente

Risposta breve: dalla radice del progetto esegui npx shadcn@latest init, poi aggiungi un componente con npx shadcn@latest add button. Non installi un pacchetto: il CLI copia file TypeScript nel tuo repository.

Cosa serve prima di eseguire init

• Un progetto con package.json e Tailwind CSS già configurato: la guida 2026 assume Tailwind CSS 4.
• Un alias di import come @/* in tsconfig.json o jsconfig.json.
• Il file CSS globale dove vivono i token del tema.

Se manca uno dei tre, init scrive comunque i file ma gli import non risolvono. L'errore tipico è Cannot find module '@/lib/utils', e la causa è nell'alias, non nel componente.

# 1. inizializza configurazione, dipendenze e token
npx shadcn@latest init

# 2. aggiungi il primo componente
npx shadcn@latest add button

Cosa scrive init nel progetto

• components.json: alias, percorso del CSS, base color e stile.
• lib/utils.ts: la funzione cn che unisce le classi.
• Le variabili CSS del tema nel file globale, più le dipendenze richieste dal componente.

Il comando non crea un pacchetto @shadcn/ui: i componenti finiscono in components/ui e da quel momento sono codice tuo. La licenza di shadcn/ui è MIT (repository), come Tailwind CSS e Radix UI, le primitive su cui poggiano i componenti.

L'esempio concreto: components.json

Il file che decide tutto è components.json, scritto da init e letto da ogni add. Se il percorso tailwind.css punta a un foglio che non esiste, i token non arrivano e i componenti escono senza colore.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Leggi tre chiavi e sai se il progetto è coerente: aliases.ui decide dove finiscono i componenti, tailwind.css dove finiscono i token, tailwind.config resta vuoto con Tailwind CSS 4. Se una delle tre non corrisponde alla cartella reale, correggi prima di aggiungere il secondo componente.

Il controllo che evita la maggior parte dei problemi

npx shadcn@latest info
npx shadcn@latest add card --dry-run

info stampa la configurazione che il CLI legge davvero: se il percorso CSS o l'alias sono diversi da quelli che hai in testa, fermati qui. --dry-run elenca i file senza scriverli, così vedi in anticipo se il comando vuole toccare qualcosa che hai già modificato.

Monorepo e cartelle annidate

Il CLI cerca components.json nella cartella corrente, non risale l'albero. In un monorepo esegui il comando dal workspace che lo contiene, oppure passa -c con il percorso.

# dalla radice del repository
npx shadcn@latest add card -c apps/web

Limite dichiarato

La scelta cssVariables si fa in fase di init e vale per sempre: per passare da token CSS a utility inline la documentazione ufficiale dice di cancellare e reinstallare i componenti. Decidila prima di costruire dieci schermate, non dopo.

La regola di decisione

Regola: guarda quante registryDependencies dichiara il blocco. Fino a due, add è sicuro; oltre cinque, leggi la lista e aggiungi i componenti uno per volta, così il diff resta leggibile. Il massimo nel catalogo è venti, e un comando solo scriverebbe tutto insieme.

L'errore da evitare

Rieseguire add button su un componente già modificato è l'errore più costoso: il CLI sovrascrive il file senza chiedere e le tue modifiche spariscono senza un avviso. Fai un commit prima di ogni add; se il diff contiene file che non volevi toccare, git checkout li riporta indietro.

Dove continuare

Il catalogo EneUI parte dalla libreria shadcn, con record come la sidebar, e dalle 1.556 anteprime di blocchi. Per il passo successivo leggi come funzionano i blocchi shadcn e i registry privati; per la struttura del progetto, App Router nel 2026. Il confronto tra temi è in temi shadcn gratis o premium.