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

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

// 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" }]
    }
  ]
}

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