Le registre shadcn, expliqué

Un registre shadcn est du JSON servi via HTTP. C'est tout le concept. Il n'y a pas de package à publier, pas de runtime, pas de service auquel s'inscrire : vous hébergez des fichiers à des URL, et la CLI shadcn en récupère un, lit ce qu'il déclare et écrit le résultat dans le projet de destination.

C'est ce qui le différencie d'une bibliothèque de composants. Une bibliothèque est une dépendance — vous l'installez, vous importez depuis celle-ci, et son code réside derrière un numéro de version dans node_modules. Un registre vous remet le code source. Après un shadcn add, les fichiers vous appartiennent : ils sont dans votre repo, dans votre diff, et modifiables sans fork. Le compromis est le suivant — vous assumez la maintenance et vous perdez les mises à jour automatiques — et c'est sur ce compromis que repose toute l'approche shadcn.

Vous pouvez publier un seul élément sans jamais écrire d'index. C'est l'utilisation la plus rapide et la plus utile d'un registre, et c'est l'objectif final de ce guide — mais il est important d'en connaître les champs au préalable.

• `name` — l'identifiant utilisé dans les commandes d'installation et dans registryDependencies.
• `type` — la nature de l'élément : registry:ui pour un composant, registry:block pour un bloc composé de plusieurs fichiers, registry:theme pour un ensemble de tokens, registry:style pour un style de base complet, ainsi que des variantes pour les hooks, libs, pages et fichiers.
• `files` — le code source qui sera écrit, chacun avec son propre type et un chemin target optionnel.
• `dependencies` — les packages npm dont l'élément a besoin, installés automatiquement pour vous.
• `registryDependencies` — les autres éléments de registre requis par celui-ci, par nom ou par URL. La CLI les résout, ce qui permet de gérer automatiquement l'ordre d'installation.
• `cssVars` — propriétés personnalisées CSS, divisées en theme, light et dark.
• `css` — règles CSS arbitraires, pour tout ce que les variables ne peuvent exprimer.
• `font` — polices requises par l'élément, afin que la typographie ne soit pas une étape manuelle distincte.
• `categories`, `docs`, `meta` — métadonnées pour les explorateurs, instructions post-installation et toute information personnalisée.

Les trois éléments souvent négligés sont cssVars, css et font, car presque tous les tutoriels présentent un composant. Ce sont pourtant ces trois-là qui transforment un registre, d'un simple mécanisme de distribution de composants en un mécanisme de distribution de design system.

En voici un exemple concret, actuellement en ligne — l'élément derrière le kit gratuit Ambient Sage, raccourci pour la lisibilité. Aucun de ses composants n'est un composant au sens strict :

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "ambient-sage",
  "type": "registry:theme",
  "title": "Ambient Sage",
  "description": "A warm-sage neutral-surface kit with a single vivid yellow accent.",
  "categories": ["minimal", "warm-neutral", "flat", "calm", "yellow-accent"],
  "cssVars": {
    "theme": {
      "font-heading": "'Plus Jakarta Sans', sans-serif",
      "font-mono": "'JetBrains Mono', monospace",
      "radius-button": "0.75rem",
      "radius-card": "1.25rem",
      "shadow-sm": "none",
      "duration": "180ms",
      "ease": "cubic-bezier(0.4,0,0.2,1)"
    },
    "light": {
      "background": "72 19% 95%",
      "foreground": "84 10% 10%",
      "card": "70 11% 89%",
      "primary": "54 98% 66%"
    },
    "dark": {
      "background": "84 10% 10%",
      "foreground": "68 13% 88%",
      "card": "80 9% 14%"
    }
  },
  "font": { "heading": "Plus Jakarta Sans", "mono": "JetBrains Mono" },
  "docs": "Use the semantic tokens; do not add a second accent."
}

Trois points sont à noter. cssVars.theme contient la partie non colorimétrique d'un design system — rayons (radii), ombres, timing d'animation, polices — là où la plupart des « générateurs de thèmes » s'arrêtent et commencent à dénaturer le design. light et dark sont des objets distincts plutôt qu'une seule palette avec une inversion. Enfin, docs contient une instruction écrite, que le CLI affiche après l'installation et qu'un agent de code peut lire.

L'installation se fait en une seule commande et elle repeint un projet existant plutôt que d'y ajouter des éléments : chaque composant référençant déjà bg-primary ou text-muted-foreground adopte les nouvelles valeurs sans modification manuelle.

npx shadcn add https://identityforge.io/r/ambient-sage.json

1. 1

   Rédiger un fichier d'élément

   Commencez par un seul fichier registry-item.json. Vous n'avez pas besoin de registry.json, d'une étape de build ou d'un monorepo pour être utile — un index n'est pertinent que lorsque vous avez plusieurs éléments et que vous souhaitez un espace de noms (namespace).

2. 2

   L'héberger sur une URL stable

   N'importe quel hébergeur statique convient. L'important est que l'URL ne change pas : c'est la commande d'installation, elle se retrouve donc copiée dans des README, des prompts et des configurations d'agents.

   Copy

   https://identityforge.io/r/<slug>.json

3. 3

   Configurer le type de contenu et le CORS

   Servez le fichier en application/json. Si un navigateur doit le récupérer — via un explorateur de registre ou un outil de prévisualisation — envoyez également des headers CORS permissifs. C'est la raison la plus courante pour laquelle un élément qui semble correct ne s'installe pas.

4. 4

   Tester avec le CLI réel

   Installez-le dans un projet de test avant de publier l'URL. Une erreur de schéma se manifeste ici en quelques secondes, alors qu'elle n'apparaîtra que dans un rapport de bug après plusieurs semaines.

   Copy

   npx shadcn add https://example.com/r/thing.json

Une URL brute suffit pour un seul élément. Dès que vous en publiez plusieurs, un espace de noms est préférable : configurez le registre une fois dans components.json et installez par nom court, avec plusieurs registres côte à côte.

Les registres privés sont supportés et le CLI accepte quatre modes d'authentification : un token bearer (OAuth 2.0), une clé API, l'authentification basic et un paramètre de requête. Le choix dépend de votre hébergement, et non de shadcn.

registryDependencies permet à un élément de dépendre d'autres éléments, même à travers différents registres. Le CLI résout le graphe et installe les éléments dans l'ordre des dépendances : ainsi, un bloc nécessitant un bouton recevra le bouton en premier, que vous l'ayez demandé ou non.

Le mode de panne à connaître est la boucle : deux éléments qui se déclarent mutuellement comme dépendances. Rien ne se résout, et l'erreur pointe vers l'étape de résolution plutôt que vers votre JSON. Si une installation freeze ou échoue sur un élément qui semble correct, dessinez les flèches de dépendance sur papier avant toute autre tentative de débogage.

C'est la question la plus posée et la moins traitée concernant les registres, et elle a trois réponses. shadcn maintient un index de registres open-source disponibles nativement. registry.directory est un explorateur indépendant qui permet de parcourir et de prévisualiser les éléments avant l'installation. Enfin, un nombre croissant de projets individuels — ce site inclus — publient une URL d'élément stable et se contentent de la documenter.

Cette troisième catégorie est facile à négliger et mérite d'être vérifiée en priorité : si un projet que vous appréciez possède un thème ou un ensemble de composants qui vous intéresse, cherchez un chemin /r/ avant de supposer que vous devez copier le CSS à la main.

Un agent de code à qui l'on donne trois couleurs de marque dispose de trois valeurs et d'environ vingt-cinq autres non définies : états hover et active, texte atténué, bordures, ring, destructive, séries de graphiques, et tout cela à nouveau pour le mode sombre. L'agent les complète avec compétence, mais différemment à chaque fois, ce qui crée précisément la dérive qu'un design system est censé empêcher.

Un élément de registre comble ce fossé en une seule commande, et il est portable d'une manière unique dans cet écosystème : v0 accepte un registre comme source de design system, Bolt peut en installer un depuis son terminal intégré, et Cursor ou Claude Code peuvent exécuter la même commande dans votre repo. Une URL, quatre outils, aucune intégration spécifique par outil. La partie rédactionnelle — ce qu'il ne faut jamais faire, quelle variante attribuer à une action destructive — doit figurer à côté dans un DESIGN.md, car cssVars répond à la question *quelle couleur* et seule la prose répond à la question *quoi ne jamais faire*.