What is shadcn registry?

The shadcn CLI does not only install shadcn/ui's own components. It installs any item described in the registry format: a JSON document that lists the item's source files, npm dependencies, other registry items it needs, and optional CSS variables. Anyone can host a registry, whether it is a public library, a company design system or a private set of blocks. In practice a registry is a folder of JSON files served over HTTP, usually under an /r/ path.

How it works

Each installable item is a registry item document. The CLI fetches it, installs the npm dependencies, resolves registryDependencies recursively, rewrites import paths to match the aliases in your components.json, and writes the files into your project.

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "badge",
  "type": "registry:ui",
  "title": "Badge",
  "dependencies": ["@base-ui/react", "class-variance-authority"],
  "registryDependencies": ["utils"],
  "files": [
    {
      "path": "registry/ui/badge.tsx",
      "type": "registry:ui",
      "target": "components/ui/badge.tsx",
      "content": "..."
    }
  ]
}

• type tells the CLI what the item is: registry:ui for a component, registry:block for a composed section, and other types for hooks, lib files, pages and themes.
• dependencies are npm packages, installed with your package manager.
• registryDependencies are other items, either shadcn names like utils or full URLs to items in any registry.
• files carry the source inline in content, so one request is enough.
• An index file, registry.json, lists every item and is what shadcn build reads to generate the item files.

Installing from a registry

# by URL
npx shadcn@latest add https://ui.minidev.pro/r/badge.json

# or register a namespace once in components.json:
#   "registries": { "@minidev": "https://ui.minidev.pro/r/{name}.json" }
npx shadcn@latest add @minidev/badge

Why it matters

Registries turn copy-paste code into a distribution channel with dependency resolution. Consumers get editable source and no runtime package to track, and publishers ship updates by redeploying JSON. The same files are easy for AI coding tools to read. Build your own shadcn registry covers hosting one, from registry.json to deployment.

How MiniDev UI uses it

Every MiniDev component, block and page is a registry item at https://ui.minidev.pro/r/<name>.json, generated from its source, and the full index lives at /r/registry.json. Each docs page, such as Code block, shows the exact install command with a copy button. Items that build on other MiniDev components list them as full URLs in registryDependencies, so installing a composed component such as an activity feed also brings in the avatar and list item it uses.