# Component Registry JSON Example: Ship Installable UI

> By Lawrence Arya, Founder & CEO of VP0. Published 2026-06-04. 6 min read.
> Source: https://vp0.com/blogs/component-registry-json-example

A component registry is just a JSON contract the CLI reads, so getting the fields right is what makes your components installable.

**TL;DR.** A component 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 fields right and a single command pulls your component plus its requirements into a project. Start your components from a finished VP0 design, the free, AI-readable design library that AI builders copy from, so what you publish to the registry is well-formed and accessible.

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](https://ui.shadcn.com/docs/registry) 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](https://react.dev) component plus its requirements into a project. Start your components from a finished design on [VP0](https://vp0.com), 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](https://survey.stackoverflow.co/2024/) 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

```json
{
  "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](/blogs/react-component-marketplace/) and [where to find copy-paste React components](/blogs/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](/blogs/auto-generate-playwright-tests-for-shadcn/), and for a CMS workflow see [the best MCP for Builder.io visual CMS](/blogs/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.

## Frequently asked questions

### 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.

---
*Published on the [VP0 Journal](https://vp0.com/blogs). Free to read, index and cite with attribution.*