The shadcn Registry Protocol

The shadcn/ui registry protocol is one of the most underappreciated innovations in the React ecosystem. It solves a fundamental problem with component libraries: how do you distribute components as source code instead of compiled packages?

The problem with npm packages

Traditional component libraries ship as npm packages. You install them, import them, and use them as black boxes. This works until you need to customize something beyond what the API exposes. Then you are fighting the library — overriding styles, wrapping components, or forking the entire package.

shadcn/ui took a different approach: instead of installing a package, you copy the component source code into your project. You own it. You can modify it however you want. But copying files manually does not scale, which is where the registry protocol comes in.

How the protocol works

The registry protocol is a JSON-based schema that describes components and their dependencies. Each component is represented as a registry item — a JSON file that the CLI can fetch and process.

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "pricing-card",
  "type": "registry:component",
  "title": "Pricing Card",
  "description": "A pricing tier card component.",
  "dependencies": ["clsx"],
  "registryDependencies": ["button"],
  "files": [
    {
      "path": "registry/new-york/pricing-card.tsx",
      "type": "registry:component",
      "content": "// full component source code"
    }
  ]
}

The install flow

When you run the install command, the CLI performs a straightforward sequence:

npx shadcn add https://kit.newth.ai/r/pricing-card.json

1. Fetch the registry JSON from the URL
2. Resolve registryDependencies recursively
3. Install any npm dependencies not already in the project
4. Write the source files to the configured component directory

The result is source code in your project that you fully own. No runtime dependency on the registry. No version lock-in. Just files.

Why this matters for the ecosystem

The registry protocol turns component distribution into a URL-based concern. Anyone can host a registry. You do not need to publish to npm. You just need a web server that serves JSON files.

• Teams can run private registries — internal component libraries distributed via the same protocol
• Composition over inheritance — registries can depend on other registries
• No version conflicts — you own the source, so there are no peer dependency issues

Extending with AI context

The registry protocol gives you component distribution. But distribution alone is not enough when AI tools are generating half your code. The tool that writes your components needs to understand how to use them.

This is where kit extends the protocol. Alongside each component in the registry, kit ships AI context packs — structured descriptions of component APIs, composition patterns, and design constraints that AI tools can consume.

# Install the component
npx shadcn add https://kit.newth.ai/r/button.json

# AI tools now know about Button:
# - Available props: variant, size, disabled
# - Variants: primary, secondary, ghost, outline
# - Constraints: use primary for main CTA only

The registry protocol created the foundation for source-code component distribution. The next step is making that distribution AI-aware. That is what we are building.