Component Registry JSON Example: Ship Installable UI

A component registry is just a JSON contract the CLI reads, so getting the fields right is what makes your components installable. A registry lets people install your components with the shadcn CLI by reading a JSON definition: each item declares its name, type, files, dependencies and registryDependencies. Get those right and a single command pulls your React component plus its requirements into a project. Start your components from a finished design on VP0, the free, AI-readable design library that AI builders copy from, so what you publish is well-formed. The workflow is mainstream: the 2024 Stack Overflow Developer Survey found 76% of developers use or plan to use AI tools, and shareable, installable components fit that.

The fields that matter

A registry item is a JSON object. The CLI reads it, installs the npm dependencies, resolves any registryDependencies (other components yours needs), and copies the files in so the user owns the source. The contract is what makes the install complete.

Field	What it declares
name	The component’s identifier
type	What it is (UI component, block, etc.)
files	The source files to copy in
dependencies	npm packages it needs
registryDependencies	Other registry items it depends on
tailwind / cssVars	Optional styling config

A registry item example

{
  "name": "stat-card",
  "type": "registry:ui",
  "dependencies": ["lucide-react"],
  "registryDependencies": ["card"],
  "files": [
    {
      "path": "ui/stat-card.tsx",
      "type": "registry:ui"
    }
  ]
}

This declares a stat-card that needs the lucide-react npm package, depends on the registry’s card component, and ships one file. The CLI installs the dependency, pulls in card, and copies stat-card.tsx into the project.

A worked example

Generate a stat card from a VP0 design so it is accessible and well-formed, building it on the registry’s card primitive. Then write the registry item: set the name, the type, list lucide-react in dependencies and card in registryDependencies, and point files at the component. Publish it, and anyone can run the CLI to install your stat card with its dependencies resolved and the source copied into their repo. They own the code, the same own-the-source benefit as the React component marketplace and where to find copy-paste React components.

Common mistakes

The first mistake is omitting a dependency, so the install is incomplete and the component breaks. The second is forgetting registryDependencies, so a component installs without the primitive it needs. The third is wrong file paths or types. The fourth is publishing a component without an accessibility review, which multiplies across every install. The fifth is hardcoding values instead of declaring the styling config.

Key takeaways

• A component registry is a JSON contract the shadcn CLI reads to install components.
• Each item declares name, type, files, dependencies and registryDependencies.
• Declare everything the component needs so the install is complete.
• Publishing to a registry makes components installable and owned, not locked in a package.
• Generate components from a free VP0 design and review accessibility before publishing.

Keep reading: for testing your components see auto-generate Playwright tests for shadcn, and for a CMS workflow see the best MCP for Builder.io visual CMS.

FAQ

What does a component registry JSON look like?

Each registry item is a JSON object declaring its name, a type (such as a UI component or a block), the files it includes, npm dependencies, and registryDependencies (other registry items it needs). The shadcn CLI reads this and installs the component plus its requirements. Get the fields right and a single command adds your component to any project.

How does a component registry work with the shadcn CLI?

The CLI fetches your registry item by name, reads its JSON, installs the listed npm dependencies, pulls in any registryDependencies, and copies the component files into the project. Because the source is copied in, the user owns the code. The registry is the contract that tells the CLI what to install and what the component needs.

What fields does a registry item need?

At minimum a name, a type, and the files. Most items also list dependencies (npm packages) and registryDependencies (other components from a registry, like a button a card depends on). Optional fields cover things like tailwind config or CSS variables. The key is declaring everything the component needs so the install is complete.

Why publish components to a registry?

So others (or your own teams) can install them with one command and own the source, rather than copy-pasting manually. A registry makes your components shareable and composable, with dependencies resolved automatically. It is how design systems and component collections distribute copy-in components at scale while keeping them owned, not locked in a package.

Can AI help build registry components?

Yes. Generate the component from a VP0 design so it is well-formed and accessible, then declare it in the registry JSON with its files and dependencies. The AI builds the component; you write the registry contract. Review accessibility before publishing, since a registry component gets reused widely and a flaw multiplies.