All posts
Product design

shadcn Registry: Distributing Your Own Design System to AI Tools

How to build and publish a custom shadcn registry so v0, Cursor, the shadcn MCP server and your teammates install your design system, not generic defaults.

By Mehdi Hassan9 min read

The short answer

A shadcn registry is a set of JSON files, generated from a registry.json manifest, that lets the shadcn CLI install your own components, tokens and utilities into any project. Publishing your design system as a registry means teammates, the shadcn MCP server and tools like v0 pull your branded versions instead of the stock shadcn/ui defaults.

Key takeaways

  • A registry is just a registry.json manifest plus built JSON files served from a URL, by default from public/r.
  • Ship a theme item with your tokens first, so every component installs on-brand.
  • Use registryDependencies so installing one block pulls in every component it needs.
  • Namespaces in components.json let people and agents install with a short name like @acme/button.
  • Open in v0 has limits: no namespaced registries and no cssVars, css or envVars items, per the shadcn docs.

Part of Design Systems for Startups: What You Need, When and How to Build One

What is a shadcn registry?

A shadcn registry is a distribution format for code. You describe your components, hooks, utilities, themes and pages in a registry.json file, run the shadcn CLI's build command, and serve the output as JSON files from any URL. Anyone with the shadcn CLI can then install those items into their project, with the source code landing in their repo.

It's the same mechanism ui.shadcn.com uses to ship its own components. The shadcn docs describe the registry as working with any project type and framework, not only React. For a startup, the practical use is narrower: it's the cleanest way to make your themed version of shadcn/ui the version everyone installs. If you haven't decided whether to stay on shadcn/ui or go custom, start with our shadcn/ui vs custom design system comparison, and see the startup design system guide for where a registry fits in the bigger picture.

Why publish your design system as a custom shadcn registry?

Publish your design system as a custom shadcn registry when more than one project, person or AI tool needs your components. Without one, every new repo starts from stock shadcn/ui and someone re-themes it by hand, or an agent installs the default Button and your brand quietly disappears.

  • Teammates run one install command and get your Button, with your variants and tokens, instead of copying files between repos.
  • Coding agents using the shadcn MCP server can browse, search and install from registries you configure, according to the shadcn docs, so an agent asked for a dialog gets yours.
  • v0 can open a public registry item through an Open in v0 link, so generated screens start from your components.
  • Marketing site and product can share the same primitives without a published npm package or a monorepo.

The difference from an npm package matters. A registry copies source into the project, so each team can still edit a component locally. That's ideal for startups that want a shared base without locking everyone to one version, and less ideal if you need strict, versioned control over every consumer.

What can a shadcn registry contain?

A shadcn registry can contain any file a project needs, typed by what it is. The type tells the CLI how to resolve the item and where to put its files. These are the main item types listed in the shadcn registry-item documentation.

Type

What it's for

Design system example

registry:ui

UI components and single-file primitives

Your themed Button, Input, Dialog

registry:component

Simple components

A PricingToggle or Logo

registry:block

Complex components made of several files

A settings page section or login form

registry:theme

Themes

Your color, radius and type tokens

registry:style

Registry styles

A full style that sets the base for every item

registry:hook and registry:lib

Hooks and utilities

useCopyToClipboard, a cn helper

registry:page and registry:file

Routes and other files, which need a target path

A docs page, a rules file for agents

registry:font

Fonts

Your brand typeface setup

Items can also carry cssVars grouped by theme, light and dark, css rules such as keyframes and utilities, npm dependencies, and a docs message the CLI shows after install. The cssVars field is how your design tokens travel with the components.

How do you build a shadcn registry step by step?

To build a shadcn registry, write a registry.json manifest at the root of your project, describe each item and its files, run the build command, and serve the output. The steps below follow the shadcn getting-started docs; check them for the current schema before you begin.

  1. Create registry.json

    At the project root, add a registry.json with a $schema pointing to the shadcn registry schema, plus name, homepage and an items array. A Next.js app works well as the host, because the build output is served as static files.

  2. Add a theme item first

    Make a registry:theme item whose cssVars hold your semantic tokens for light and dark. Every component should depend on it, so nothing installs unstyled.

  3. Describe each component

    For each item, set name, type, title, a one-sentence description and files, where each file has a path and a type. Write descriptions as 'use this for…', because the MCP server and agents use them to pick items.

  4. Declare dependencies

    List npm packages under dependencies and other registry items under registryDependencies. A login block that lists your button, input and theme installs all three in one command.

  5. Build the registry

    Run pnpm dlx shadcn@latest build. By default it writes one JSON file per item to public/r, such as public/r/button.json. Use the --output option to change the folder.

  6. Serve and test

    Deploy the host app, then in a fresh project run pnpm dlx shadcn@latest add with the full URL of an item. Check that the theme, files and dependencies all arrive.

Hypothetical example: a three-item starter registry

For example, suppose a startup called Acme wants its product and marketing repos to share components.

Its registry.json has three items. acme-theme is a registry:theme with cssVars for background, foreground, primary, muted and destructive in light and dark. button is a registry:ui item with one file, its themed Button, and acme-theme in registryDependencies. login-form is a registry:block with two files and button, an input item and acme-theme as registry dependencies.

After the build, a new repo installs login-form and gets the tokens, the button, the input and the form in one command. Each description says when to use the item, so an agent searching for 'sign in form' finds login-form rather than building one.

How do teammates and AI tools install from your registry?

Teammates and AI tools install from your registry by URL or by namespace. The simplest route is passing a full item URL to the add command. For daily use, a namespace is shorter and is what agents work with best.

Namespaces live under the registries key in components.json. Each key starts with @ and maps to a URL template containing {name}, which the CLI replaces with the item name. The shadcn docs show adding the namespace to components.json, then installing with pnpm dlx shadcn@latest add @acme/button. Several items can go in one command.

For agents, the shadcn MCP server reads those same registries from components.json. The docs list setup for Claude Code, Cursor, VS Code and Codex, with an init command for Claude Code. Once it's connected, an agent can search your registry and install items by name, which pairs well with a short rules file telling it to check the registry before writing a new component.

How do you keep a private shadcn registry secure?

Keep a private shadcn registry secure by requiring a token on every request and passing it from an environment variable, never from a committed file. The namespace config supports an object form with a URL, headers and params, and the shadcn docs show values like ${REGISTRY_TOKEN} being expanded from the environment.

  • Use headers for the CLI and MCP. A Bearer token or API key header keeps secrets out of URLs and logs.
  • Return 401 on a bad token. The shadcn docs say the CLI and Open in v0 both show a message for 401 responses, which makes failures obvious.
  • Keep v0 items separate. Since v0 only supports a token query parameter, expose a small public or token-gated set for v0 and keep the rest behind headers.
  • Don't ship secrets in envVars. The docs describe envVars as development or example values added to .env files, not production values.

What mistakes break a shadcn design system registry?

The mistakes that break a shadcn design system registry are almost always about drift: components that install without tokens, items that don't declare what they need, and a registry that falls behind the design files.

  • Missing registryDependencies. A block that silently assumes your Button exists installs broken in a fresh project. Test every item in an empty repo.
  • Vague descriptions. 'Card component' gives an agent nothing. 'Use for a clickable summary of one record; not for marketing content' does.
  • Tokens out of sync with Figma. Generate the theme item's cssVars from the same token source as your Figma variables, using the Figma variables to code pipeline, so design and registry can't disagree.
  • No changelog. Because installs copy source, consumers don't get updates automatically. Note changes in each item's docs message and in your repo, so teams know when to re-add.

Should your startup build a shadcn registry?

Your startup should build a shadcn registry once you have two or more repos that share UI, or when coding agents write a meaningful share of your interface. Before that, a themed components folder in one repo does the same job with less setup.

Frequently asked questions

Is a shadcn registry the same as an npm package?
No. An npm package installs compiled code into node_modules and updates when you bump a version. A shadcn registry copies source files into your project, where you own and can edit them. That makes a registry easier to customize per project, but updates don't arrive automatically, so you re-add items when the registry changes.
Can I host a shadcn registry on GitHub?
The shadcn docs include a page on turning a GitHub repository into a registry, and registryDependencies can reference GitHub addresses. Many teams still prefer a small hosted app, because it serves the built JSON at a stable URL and makes token-based auth simple. Check the current docs for the GitHub setup details.
Does a shadcn registry work without Tailwind?
The registry format itself is framework-agnostic according to the shadcn docs, so it can distribute any files. In practice, most registry components are built on Tailwind and CSS variables, like shadcn/ui itself. If your design system uses another styling approach, the registry can still ship it, but you lose the cssVars theming most items rely on.
How do I make AI agents use my registry instead of stock shadcn/ui?
Configure your namespace in components.json, connect the shadcn MCP server to your agent, and add a line to your rules file telling the agent to search your registry before writing or installing any component. Clear item descriptions that say when to use each component help the agent pick the right one.
Can a registry include more than components?
Yes. Registry items can be hooks, utilities, themes, fonts, pages and arbitrary files with a target path. Teams use that to ship shared config, such as a token theme or an agent rules file, so every new project starts with the same foundations as well as the same components.

· CEO & Design Director

Copywriter, designer and developer, and founder of Designify Studio. Over five years, 60+ projects across 14+ industries, for startups that have raised $300M+.

Want this done for you? Monthly retainer, $6,000.

Your ongoing design and development team, for products that keep shipping. $6,000, per month, flat fee. Book a free 30-minute call to see if it fits.

Schedule Call