# How to add a shadcn block without breaking the theme

Install the block on a branch, inspect the tokens it uses and read the diff: a block becomes project code, not a versioned package.

> Page: https://ui.eneawork.it/blog/come-aggiungere-un-blocco-shadcn
> Markdown: https://ui.eneawork.it/blog/come-aggiungere-un-blocco-shadcn.md

*2026-11-01*

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.

La domanda «Add both !important & selector strategy for tailwind configuration» vale 122 voti su Stack Overflow, misurata il 31 ottobre 2026 nel file docs/keyword-data.json: fonte. I conteggi del catalogo EneUI, misurati da /api/stats il 1 novembre 2026. I comandi sotto girano in locale e non richiedono un account.

## 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

# 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

## 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.

## FAQ

### Un blocco si aggiorna da solo?

No. I file vengono copiati nel progetto e non hanno un meccanismo di aggiornamento: per allinearti al registry devi reinstallare il blocco e rivedere il diff a mano.

### Perché il blocco resta grigio in dark mode?

Perché usa classi con colori fissi, come bg-zinc-100, invece dei token semantici. Il tema scuro cambia i token, non le palette scritte a mano: la correzione è nel blocco.

### Posso installare solo una parte del blocco?

Sì. Dopo l'installazione elimina i file o i sotto-componenti che non usi, purché nessun import del progetto continui a puntarci.

### Cosa fa esattamente --dry-run?

Mostra i file che il comando scriverebbe e le dipendenze che aggiungerebbe, senza modificare il progetto. È il modo più rapido per scoprire se il blocco tocca componenti condivisi.

### Il blocco può sovrascrivere i miei componenti ui?

Non per impostazione predefinita: il CLI chiede prima di sostituire un file esistente. Con --overwrite o -o la sostituzione avviene senza domande, quindi evitalo su un progetto già personalizzato.