Smart Registry

A zero-configuration (no registry.json required), shadcn add / open in v0 compatible registry builder.

The best configuration is no configuration. Focus on developing building blocks, components, and pages, rather than spending time configuring the registry.

What is Zero-Configuration?

Simplify your registry.json by removing properties like registryDependencies, dependencies, and files. If you don't need to add custom properties or extend default ones, you can even delete the registry.json file entirely.

{
  "items": [
    {
      "name": "dialog",
      "type": "registry:ui",
-      "registryDependencies": [
-        "button"
-      ],
-      "dependencies": [
-        "@radix-ui/react-dialog"
-      ],
-      "files": [
-        {
-          "path": "registry/default/ui/dialog.tsx",
-          "type": "registry:ui"
-        }
-      ]
-    }
  ]
}

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "dialog",
  "type": "registry:ui",
  "dependencies": ["@radix-ui/react-dialog"],
  "files": [
    {
      "type": "registry:ui",
      "target": "components/ui/button.tsx",
      "content": "...",
      "path": "registry/default/ui/button.tsx"
    },
    {
      "type": "registry:ui",
      "target": "components/ui/dialog.tsx",
      "content": "...",
      "path": "registry/default/ui/dialog.tsx"
    },
    {
      "type": "registry:lib",
      "target": "lib/utils.ts",
      "content": "...",
      "path": "registry/default/lib/utils.ts"
    }
  ]
}

Manual maintenance of registry.json files can lead to errors due to missing dependencies or files, or wrongful addition of unnecessary ones. Smart Registry reduces these risks by automating the detection and generation of the all-in-one r/registry.json and r/<registry-item>.json entries, making registry management more efficient.

Table of Contents

• Usage
  • Configure Alias
  • Automatic Detection
  • From Specific Files
  • From Specific Directories
• How it Works
• Extending Properties
  • With zero-configuration
  • Add custom properties
  • Additional files to include
  • External registry dependencies
  • Specify dependency version
• Directory Structure

Usage

Automatic Detection

If your project contains a registry, components, or src/components directory, Smart Registry will automatically detect and generate the necessary registry files. For more details, refer to the directory structure section.

npx smart-registry

From Specific Files or Directories

If you want to generate the registry from specific files or directories, you can pass them as arguments.

npx smart-registry path/to/file.ts path/to/directory ...

How it Works

Let's take the following directory structure to understand how Smart Registry works.

registry/
└── default/
    ├── lib/
    │   └── utils.ts
    └── ui/
        ├── button.tsx
        └── dialog.tsx

1. Smart Registry will scan the registry directory and its sub-directories to find all the files. If no registry directory is found, it will scan the components or src/components directory.
2. For each file, it will generate a <registry-item>.json file by reading the file's content and extracting the imports for registry dependencies, dependencies, and files recursively.
3. It will then generate a registry.json file by combining all the <registry-item>.json files with all the properties required for shadcn add or open in v0.

public/
└── r/
    ├── button.json
    ├── dialog.json
    ├── registry.json
    └── utils.json

Extending Properties

You can add/extend the generated public/registry.json and public/r/<registry-item>.json files by creating a registry.json file in the root of your project. The properties in this file will be merged with the generated properties.

We will consider the dialog component with the following directory structure to demonstrate the extension of properties.

registry/
└── default/
    ├── lib/
    │   └── utils.ts
    └── ui/
        └── dialog.tsx

With zero-configuration.

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "dialog",
  "type": "registry:ui",
  "dependencies": ["@radix-ui/react-dialog"],
  "files": [
    {
      "type": "registry:ui",
      "target": "components/ui/dialog.tsx",
      "content": "...",
      "path": "registry/default/ui/dialog.tsx"
    },
    {
      "type": "registry:lib",
      "target": "lib/utils.ts",
      "content": "...",
      "path": "registry/default/lib/utils.ts"
    }
  ]
}

Add custom properties.

{
  "items": [
    {
      "name": "dialog",
      "type": "registry:ui",
+      "meta": {
+        "tags": ["dialog", "modal"]
+      }
    }
  ]
}

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "dialog",
  "type": "registry:ui",
  "dependencies": ["@radix-ui/react-dialog"],
  "files": [
    {
      "type": "registry:ui",
      "target": "components/ui/dialog.tsx",
      "content": "...",
      "path": "registry/default/ui/dialog.tsx"
    },
    {
      "type": "registry:lib",
      "target": "lib/utils.ts",
      "content": "...",
      "path": "registry/default/lib/utils.ts"
    }
  ],
+  "meta": {
+    "tags": ["dialog", "modal"]
+  }
}

Additional files to include.

{
  "items": [
    {
      "name": "dialog",
      "type": "registry:ui",
+      "files": [
+        {
+          "type": "registry:ui",
+          "path": "registry/default/ui/button.tsx"
+        }
+      ]
    }
  ]
}

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "dialog",
  "type": "registry:ui",
  "dependencies": ["@radix-ui/react-dialog"],
  "files": [
+    {
+      "type": "registry:ui",
+      "target": "components/ui/button.tsx",
+      "content": "...",
+      "path": "registry/default/ui/button.tsx"
+    },
    {
      "type": "registry:ui",
      "target": "components/ui/dialog.tsx",
      "content": "...",
      "path": "registry/default/ui/dialog.tsx"
    },
    {
      "type": "registry:lib",
      "target": "lib/utils.ts",
      "content": "...",
      "path": "registry/default/lib/utils.ts"
    }
  ]
}

External registry dependencies.

{
  "items": [
    {
      "name": "dialog",
      "type": "registry:ui",
+      "registryDependencies": ["button"]
    }
  ]
}

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "dialog",
  "type": "registry:ui",
  "dependencies": ["@radix-ui/react-dialog"],
  "files": [
    {
      "type": "registry:ui",
      "target": "components/ui/dialog.tsx",
      "content": "...",
      "path": "registry/default/ui/dialog.tsx"
    },
    {
      "type": "registry:lib",
      "target": "lib/utils.ts",
      "content": "...",
      "path": "registry/default/lib/utils.ts"
    }
  ],
+  "registryDependencies": ["button"]
}

Specify dependency version.

Note: Only add the dependency that you want to specify the version for. The rest of the dependencies will be automatically added.

{
  "items": [
    {
      "name": "dialog",
      "type": "registry:ui",
+      "dependencies": ["@radix-ui/react-dialog@1.0.0"]
    }
  ]
}

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "dialog",
  "type": "registry:ui",
-  "dependencies": ["@radix-ui/react-dialog"],
+  "dependencies": ["@radix-ui/react-dialog@1.0.0"],
  "files": [
    {
      "type": "registry:ui",
      "target": "components/ui/dialog.tsx",
      "content": "...",
      "path": "registry/default/ui/dialog.tsx"
    },
    {
      "type": "registry:lib",
      "target": "lib/utils.ts",
      "content": "...",
      "path": "registry/default/lib/utils.ts"
    }
  ]
}

Directory Structure

For registry directory.

• Use direct name for default registry.

registry/
├── blocks/
│   └── toasty.tsx
├── components/
│   └── toaster.tsx
├── hooks/
│   └── use-toast.ts
├── lib/
│   └── utils.ts
└── ui/
    └── toast.tsx

• Or use default sub-directory for default registry.

registry/
└── default/
    ├── blocks/
    │   └── toasty.tsx
    ├── components/
    │   └── toaster.tsx
    ├── hooks/
    │   └── use-toast.ts
    ├── lib/
    │   └── utils.ts
    └── ui/
        └── toast.tsx

Both generate the following items in public/r directory.

public/
└── r/
    ├── toasty.json     name: toasty     target: blocks/toasty.tsx
    ├── component.json  name: toaster    target: components/toaster.tsx
    ├── use-toast.json  name: use-toast  target: hooks/use-toast.ts
    ├── utils.json      name: utils      target: lib/utils.ts
    └── toast.json      name: toast      target: components/ui/toast.tsx

For registry directory with multiple registries.

• Use <registry-name> sub-directory for named registry.

registry/
├── default/
└── new-york/
    ├── blocks/
    │   └── toasty.tsx
    ├── components/
    │   └── toaster.tsx
    ├── hooks/
    │   └── use-toast.ts
    ├── lib/
    │   └── utils.ts
    └── ui/
        └── toast.tsx

Generates the following items in public/r directory.

public/
└── r/
  ├── new-york/
      ├── toasty.json     name: new-york/toasty     target: blocks/new-york/toasty.tsx
      ├── toaster.json    name: new-york/toaster    target: components/new-york/toaster.tsx
      ├── use-toast.json  name: new-york/use-toast  target: hooks/new-york/use-toast.ts
      ├── utils.json      name: new-york/utils      target: lib/new-york/utils.ts
      └── toast.json      name: new-york/toast      target: components/ui/new-york/toast.tsx

For components directory.

• Use direct name for default registry.

blocks/
└── toasty.tsx
components/
├── ui/
│   └── dialog.tsx
└── toaster.tsx
hooks/
└── use-toast.ts
lib/
└── utils.ts

Generates the following items in public/r directory.

public/
└── r/
    ├── toasty.json     name: toasty     target: blocks/toasty.tsx
    ├── component.json  name: toaster    target: components/toaster.tsx
    ├── use-toast.json  name: use-toast  target: hooks/use-toast.ts
    ├── utils.json      name: utils      target: lib/utils.ts
    └── toast.json      name: toast      target: components/ui/toast.tsx

For components directory with multiple registries.

• Use <registry-name> sub-directory for named registry.

blocks/
└── new-york/
    └── toasty.tsx
components/
├── new-york/
│   └── toaster.tsx
└── ui/
    └── new-york/
        └── toast.tsx
hooks/
└── new-york/
    └── use-toast.ts
lib/
└── new-york/
    └── utils.ts

Generates the following items in public/r directory.

public/
└── r/
  └── new-york/
      ├── toasty.json     name: new-york/toasty     target: blocks/new-york/toasty.tsx
      ├── toaster.json    name: new-york/toaster    target: components/new-york/toaster.tsx
      ├── use-toast.json  name: new-york/use-toast  target: hooks/new-york/use-toast.ts
      ├── utils.json      name: new-york/utils      target: lib/new-york/utils.ts
      └── toast.json      name: new-york/toast      target: components/ui/new-york/toast.tsx