---
name: shadcn-registry-distribution
description: "Author and consume shadcn registries — registry.json, registry:base design systems, namespaced/private sources, and the MCP server. Production shadcn distribution: author registry.json with registry:ui, registry:component, registry:block, registry:hook, registry:lib, and registry:style items; ship registry:base full design-system payloads (tokens, cssVars, tailwind config); configure namespaced sources (@acme) and private registries with headers/auth in components.json; and drive add/install via the shadcn MCP server (get_items, get_item, add_item) plus the build command for static registry hosting."
license: MIT
---

# shadcn Registry Distribution

Ship your own shadcn components, blocks, and full design systems the same way `shadcn@latest add button` works for the official registry. This skill helps you author a compliant `registry.json`, build the per-item JSON the CLI consumes, wire up namespaced and private sources, and connect the shadcn MCP server so an agent can browse and install your items. It's for design-system maintainers and teams who want an internal component catalog rather than copy-pasting files between repos.

## When to use it

- You maintain a shared UI library and want teammates to run `npx shadcn@latest add @acme/data-table`.
- You're distributing marketing **blocks** or page templates, not just primitives.
- You need a `registry:base` payload that installs design tokens, CSS variables, and Tailwind config in one shot.
- You're standing up a private registry behind auth headers or a token-gated URL.
- You want an MCP-connected agent to discover and add your components conversationally.

## How it works

You author a `registry.json` (validated against `https://ui.shadcn.com/schema/registry.json`) listing `items`, each with a `name`, a `type`, `files`, and optional `dependencies`, `registryDependencies`, `cssVars`, and `tailwind`. Item types map to install behavior: `registry:ui`, `registry:component`, `registry:block`, `registry:hook`, `registry:lib`, `registry:style`, and `registry:base` for whole-system payloads. Run `shadcn build` to compile `registry.json` into individual `public/r/<name>.json` files the CLI fetches over HTTP.

Consumers reference items by URL or by a namespaced alias configured in `components.json` under `registries` (e.g. `@acme` → `https://acme.com/r/{name}.json`), with optional `headers` for bearer tokens or API keys on private sources.

## Example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/shadcn-registry-distribution/SKILL.md https://claudeskil.com/skills/shadcn-registry-distribution/SKILL.md

# scaffold + build
npx shadcn@latest init
npx shadcn build   # writes public/r/*.json
```

```jsonc
// registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "data-table",
      "type": "registry:component",
      "registryDependencies": ["table", "button"],
      "dependencies": ["@tanstack/react-table"],
      "files": [{ "path": "components/data-table.tsx", "type": "registry:component" }]
    }
  ]
}
```

```jsonc
// consumer components.json
{ "registries": { "@acme": { "url": "https://acme.com/r/{name}.json", "headers": { "Authorization": "Bearer ${ACME_TOKEN}" } } } }
```

Then: `npx shadcn@latest add @acme/data-table`.

## Tips & gotchas

- `registryDependencies` are resolved by the consumer's registry, not yours — list shadcn primitive names (`"button"`) for the public registry, or full URLs for cross-registry items.
- `cssVars` and `tailwind` only meaningfully apply on `registry:base` / `registry:style` installs; primitives shouldn't silently rewrite a consumer's theme.
- Serve `public/r/*.json` with correct CORS and `Content-Type: application/json`, or the CLI's fetch fails opaquely.
- Use `${ENV_VAR}` interpolation in `headers` so tokens stay out of committed `components.json`.

## FAQ

**Do consumers need my whole repo?** No — only the built JSON at the item URL. `shadcn build` packages each item's file contents inline.

**Can I gate a private registry?** Yes, via the `headers` block on the registry config; the CLI sends them on every fetch.

**How does the MCP server fit in?** It exposes your registry to an agent so it can list and add items without you hand-running CLI commands.