# Come installare shadcn/ui in un progetto esistente

Dalla radice del progetto: `init` configura Tailwind, alias e token, poi `add` copia i componenti. Cosa serve prima e cosa scrive il CLI.

> Pagina: https://ui.eneawork.it/blog/come-installare-shadcn-ui
> Markdown: https://ui.eneawork.it/blog/come-installare-shadcn-ui.md

*2026-11-01*

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.

La domanda «Difference between npx and npm» vale 1118 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. Ogni comando qui sotto gira in locale: nessun passaggio richiede un account. Lo stesso giorno, su data/blocks.json (snapshot del 31 ottobre 2026), un comando conta 1.219 blocchi su 1.556 con almeno una registryDependency: mediana 2, massimo 20.

## Cosa serve prima di eseguire init

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

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.

## FAQ

### Devo installare shadcn/ui come pacchetto npm?

No. shadcn/ui non è una dipendenza da importare: il CLI copia i file dei componenti nel progetto e da quel momento li modifichi come codice tuo, con licenza MIT.

### Funziona in un progetto con Tailwind CSS 3?

Sì, ma con un percorso separato: la documentazione corrente del 2026 assume Tailwind CSS 4 e le sue direttive CSS, mentre per un progetto fermo alla 3 esiste la sezione Legacy. Non mescolare le due guide.

### Cosa succede se manca l'alias @/*?

Il CLI scrive i file, ma gli import interni non risolvono e la build fallisce con Cannot find module. Aggiungi il percorso in tsconfig.json e reinstalla il componente.

### Posso annullare l'installazione?

Sì, se il progetto è in Git: git diff mostra i file scritti da init, git checkout li riporta indietro. Senza Git fai un backup prima di eseguire il comando.

### Quante volte va eseguito init?

Una volta per workspace che contiene un components.json. Rieseguirlo sovrascrive la configurazione solo con --force, quindi non è un comando da lanciare a ogni componente.