Generate Registry

Installation

npx shadcn@latest add @oward/generate-registry

Vue d'ensemble

Le script generate-registry est un outil d'automatisation Node.js qui génère et maintient le fichier registry.json pour un registry shadcn/ui. Il analyse automatiquement la structure de vos composants, utilitaires et styles pour créer un registry conforme au schéma officiel de shadcn/ui.

• Détection automatique des types disponibles (ui, lib, style, item, etc.)
• Extraction des dépendances npm depuis les imports ES6 et CommonJS
• Support des structures complexes avec sous-dossiers et fichiers multiples

Structure du projet

Le script s'attend à une structure de projet standard pour un registry shadcn/ui :

your-project/
├── registry.json          # Fichier généré automatiquement
└── registry/             # Dossier source des composants
    ├── ui/              # Composants UI
    ├── lib/             # Utilitaires et hooks
    ├── style/           # Styles et tokens
    └── item/            # Items complexes (blocks)

Utilisation

Commande de base

Exécutez le script depuis le répertoire racine de votre registry :

node scripts/generate-registry

Le script va :

1. Scanner le dossier ./registry/ pour détecter les types disponibles
2. Pour chaque type, analyser les fichiers et extraire les métadonnées
3. Générer automatiquement les entrées du registry avec leurs dépendances
4. Sauvegarder le fichier registry.json

Options CLI

Le script accepte plusieurs options pour personnaliser son comportement :

Exemples d'utilisation

# Exécution depuis le répertoire courant
node scripts/generate-registry

# Avec un chemin spécifique

node scripts/generate-registry --path /path/to/project

# Avec vérification du code de sortie

node scripts/generate-registry || exit 1

Les types

Le script détecte automatiquement les types de composants disponibles dans votre registry. Chaque type correspond à une catégorie de fichiers avec un rôle spécifique dans le registry shadcn/ui.

Extraction des dépendances

Le script extrait automatiquement les dépendances npm depuis vos imports. Il supporte plusieurs syntaxes :

// Import simple
import { Button } from "lucide-react";

// Import type
import type { ButtonProps } from "lucide-react";

// Import tout
import \* as React from "react";

Métadonnées des items

Le script extrait automatiquement les métadonnées des items (composants, hooks, utilitaires) pour enrichir le registry. Ces métadonnées peuvent être définies via des directives JSDoc (pour les fichiers uniques) ou via le fichier meta-registry.json (pour les items multi-fichiers).

Directives disponibles

Fichier meta-registry.json

Pour les items multi-fichiers, créez un fichier meta-registry.json à la racine de l'item. Ce fichier centralise toutes les métadonnées et est prioritaire sur les directives JSDoc.

Structure du fichier :

{
  "description": "Dashboard component with sidebar and charts",
  "author": "Your Name <[email protected]>",
  "target": "components/blocks",
  "dependencies": {
    "tailwind-merge": "^3.4.0",
    "recharts": "^2.10.0"
  },
  "registryDependencies": [
    "@namespace/button",
    "@namespace/card",
    "@namespace/chart"
  ]
}

@author

Spécifie l'auteur du composant ou de l'utilitaire.

/**
 * @author Geoffrey From Oward <[email protected]>
 */
export function Button() {
  return <button>Click me</button>;
}

@description

Définit une description claire du composant ou de l'utilitaire.

/**
 * @description Un bouton personnalisable avec support des variantes
 * @author Your Name <[email protected]>
 */
export function Button() {
  return <button>Click me</button>;
}

@docs

Affiche un message ou de la documentation personnalisée lors de l'installation du composant via la CLI shadcn. Utile pour indiquer les prérequis, configuration requise, ou instructions de setup.

/**
 * @docs Pour obtenir une clé API OPENAI_API_KEY, créez un compte sur https://platform.openai.com
 * @description Composant de chat avec IA
 */
export function AIChat() {
  return <div>AI Chat</div>;
}

@packages

Spécifie les versions des dépendances npm. Par défaut, les dépendances sont extraites automatiquement sans version. Utilisez cette directive pour forcer une version spécifique.

Deux syntaxes JSDoc sont supportées : multi-ligne ou inline (plusieurs packages sur une ligne).

// Syntaxe multi-ligne
/**
 * @packages tailwind-merge@^3.4.0
 * @packages lucide-react@^0.400.0
 * @packages clsx@^2.0.0
 */
export function Card() {
  return <div>Card</div>;
}

// Syntaxe inline
/**
 * @packages tailwind-merge@^3.4.0 lucide-react@^0.400.0 clsx@^2.0.0
 */
export function Alert() {
  return <div>Alert</div>;
}

@registry-dependencies

Déclare que votre composant dépend d'autres items du registry. Lors de l'installation, shadcn CLI installera automatiquement ces dépendances.

Deux syntaxes JSDoc sont supportées : multi-ligne ou inline (plusieurs dépendances sur une ligne).

// Syntaxe multi-ligne
/**
 * @registry-dependencies @oward/button
 * @registry-dependencies @oward/icon
 */
export function IconButton() {
  return <Button><Icon /></Button>;
}

// Syntaxe inline
/**
 * @registry-dependencies @oward/button @oward/input @oward/select @oward/label
 */
export function Form() {
  return <form>...</form>;
}

{
  "registries": {
    "@oward": {
      "url": "https://ui.oward.net/r/{name}.json"
    }
  }
}

@target

Personnalise le chemin de destination dans le projet de l'utilisateur. Par défaut, le chemin est généré automatiquement selon le type (components/ui/, lib/, hooks/, etc.).

/**
 * @target components/custom
 */
export function CustomButton() {
  // Sera installé dans: components/custom/custom-button.tsx
  return <button>Custom</button>;
}

Exemple avec multi-fichiers :

registry/item/dashboard/
├── dashboard.tsx
├── utils.ts
└── meta-registry.json  → {"target": "components/blocks"}

Résultat après installation:
components/blocks/
├── dashboard.tsx
└── utils.ts

@registry-ignore

Exclut un fichier de la génération du registry. Utile pour les fichiers de base (comme cn()) qui ne doivent pas être installables via la CLI shadcn.

// @registry-ignore

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Sortie du script

Le script génère un fichier registry.json conforme au schéma shadcn/ui :

{
  "name": "my-registry",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "title": "Button",
      "description": "Un bouton personnalisable avec support des variantes et des tailles",
      "author": "Your Name <[email protected]>",
      "dependencies": ["class-variance-authority"],
      "registryDependencies": ["utils"],
      "files": [
        {
          "path": "registry/ui/button.tsx",
          "type": "registry:ui",
          "target": "components/ui/button.tsx"
        }
      ]
    }
  ]
}