# Registry privati: token, namespace e installazioni in CI

Come funziona un registry shadcn privato: autenticazione, namespace, scope del token e installazione ripetibile in CI. Con gli errori che si vedono davvero.

> Pagina: https://ui.eneawork.it/blog/registry-privati-token-namespace
> Markdown: https://ui.eneawork.it/blog/registry-privati-token-namespace.md

*2026-10-31*

Un registry privato risponde a una domanda semplice: come installo un componente che non è pubblico, senza copiarlo a mano? La risposta è un endpoint JSON protetto e un token con permessi limitati.

## Il protocollo, in breve

Il CLI chiede un item a un URL, riceve un JSON con file, dipendenze e metadati, poi scrive i file nel progetto. Non c’è magia: se l’endpoint risponde 401 o 403, il CLI si ferma.

{ "registries": { "@eneui": { "url": "https://ui.eneawork.it/registry/{name}", "headers": { "Authorization": "Bearer ${ENEUI_TOKEN}" } } } }

Il namespace `@eneui` è ciò che rende leggibile il comando: `npx shadcn@latest add @eneui/hero`. Senza namespace, due registry con lo stesso nome di blocco diventano ambigui.

## Dove mettere il token

Un token che finisce nel repository è compromesso anche dopo la rimozione: la storia Git conserva i blob. Ruotalo, non cancellarlo e basta.

## Gli errori che si vedono davvero

Su EneUI il codice dei blocchi Pro è protetto lato server: la preview è pubblica, l’item del registry risponde con un errore esplicito finché non c’è accesso. Il client non riceve il codice prima del pagamento, quindi non c’è nulla da aggirare nel browser.

## Installazione ripetibile in CI

# .github/workflows/ui.yml - name: Install UI blocks run: npx shadcn@latest add @eneui/hero @eneui/pricing --yes env: ENEUI_TOKEN: ${{ secrets.ENEUI_TOKEN }}

## Namespace e provenienza

Con 1.556 blocchi da 28 registry (31 ottobre 2026) lo stesso nome può esistere in più fonti. Il namespace non è decorazione: è la parte del nome che dice da dove arriva il codice e quale licenza si applica.

La pagina /blocks mostra fonte, licenza, file e dipendenze di ogni blocco prima dell’installazione.

## FAQ

### Un registry privato richiede un server?

No, serve solo un endpoint che restituisca JSON nel formato registry. Può essere statico se non ci sono dati sensibili.

### Il token può stare nel `components.json`?

Meglio di no: il file finisce nel repository. Usa una variabile d’ambiente e lascia il segreto fuori.

### Perché serve un namespace?

Per distinguere registry diversi con lo stesso nome di item e per rendere esplicita la provenienza nel comando di install.

### Cosa significa 402 Payment Required?

Che l’item esiste ma richiede un accesso a pagamento. È diverso da 403: il token è valido, manca il diritto.

### Come ruoto un token senza rompere la CI?

Aggiungi il nuovo token come secret, verifica la pipeline, poi revoca il vecchio. Mai revocare prima del deploy.