Come aggiungere un blocco shadcn senza rompere il tema

Risposta breve: aggiungi il blocco con npx shadcn@latest add su un ramo, dopo aver letto con view e --dry-run quali file e quali token tocca. Il tema si rompe quando il blocco porta classi con colori fissi o sovrascrive una primitiva già personalizzata.

Perché un blocco può rompere il tema

Un blocco non è un componente isolato: è una sezione completa, con layout, spaziature e spesso una palette propria. Se è stato costruito su token con nomi diversi dai tuoi, le classi esistono ma leggono valori che nel tuo CSS non ci sono.

La licenza cambia con il registry di origine: shadcn/ui è MIT, i blocchi di terze parti possono essere commerciali. La pagina /blocks mostra fonte e licenza prima dell'installazione, e questo è il primo filtro da applicare.

Il percorso sicuro, in cinque passi

1. Crea un ramo: l'installazione deve essere annullabile con un comando.
2. Leggi il contenuto del blocco con view, senza scrivere nulla.
3. Prova l'installazione con --dry-run e conta i file.
4. Installa davvero, poi guarda git diff prima di aprire il browser.
5. Controlla la pagina in tema chiaro e scuro, non solo in quello in cui l'hai aperta.

# guarda i file del blocco prima di scriverli
npx shadcn@latest view ./hero-01.json

# prova l'installazione senza modificare il progetto
npx shadcn@latest add ./hero-01.json --dry-run

Se il blocco arriva da un URL o da un namespace, il comando cambia solo nel primo argomento: npx shadcn@latest add @eneui/hero. Il resto del flusso resta identico, e resta identico anche il rischio.

# installa davvero, su un ramo pulito
npx shadcn@latest add ./hero-01.json

# leggi cosa è cambiato prima di aprire il browser
git diff --stat

git diff --stat risponde a una domanda sola: quanti file ha toccato il comando e quali. Se compare un file in components/ui che non volevi modificare, il blocco dipende da una primitiva diversa dalla tua e va isolato.

Il controllo che conta: i token

{/* segue i token: cambia con il tema */}


{/* colori fissi: resta grigio anche in dark mode */}

La prima sezione segue il tema perché usa ruoli, non colori. La seconda porta una palette scritta a mano: in dark mode resta chiara, e non c'è nessun token da cambiare per correggerla. La correzione è nel blocco, non nel tema.

Cosa guardare nel diff

• Token nuovi o rinominati nel CSS globale.
• Dipendenze aggiunte al package.json.
• File in components/ui sovrascritti.
• Classi con colori fissi, che il tema non raggiunge.

Blocchi con CSS proprio

Alcuni registry spediscono il blocco con un foglio di stile e variabili che nel tuo tema non esistono. Installalo, poi mappa quelle variabili in @theme inline: senza la mappatura le utility del blocco non vengono generate e la sezione resta senza colore. La sintassi di view, add e --dry-run è documentata nella pagina CLI di shadcn/ui (licenza MIT).

Limite dichiarato

Un blocco non è un pacchetto versionato: non riceve aggiornamenti e non ha un changelog. Se lo rigeneri con --overwrite sovrascrivi anche le modifiche fatte a mano, quindi la fonte di verità resta il tuo repository, non il registry.

Dove continuare

Il catalogo EneUI elenca 1.556 blocchi con anteprima, per esempio una sezione chart e una hero. Per capire come sono organizzati leggi i blocchi shadcn in catalogo; per il tema, dark mode senza un secondo design system; per i registry, token e namespace. Il confronto tra temi pronti è in gratis o premium.