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