Imported from sextondjc/agentic (.artifacts/agent-plugins/shadcn-tailwind-system/skills/shadcn-registry/SKILL.md). Install upstream with npx skills add sextondjc/agentic --skill shadcn-registry. Copyright stays with the author.

shadcn/ui Custom Registry

Specialization

Provide expert-level guidance for designing and operating a custom shadcn/ui component registry — covering the registry.json schema, component item type taxonomy, CLI resolution and npx shadcn add <url> consumption, hosting strategies (static file host, npm package, or monorepo local), dependency declaration, and cross-project distribution patterns for org-owned components.

This skill is specialized for registry authoring and hosting. Component design and CVA variant patterns are handled by shadcn-component-design. Shared package governance and monorepo architecture are handled by shadcn-design-system. CI drift detection against the upstream shadcn registry is handled by shadcn-ci-integration.

Trigger Conditions

• A team wants to distribute org-owned components using the same npx shadcn add CLI UX as upstream shadcn components.
• A monorepo needs a private registry so downstream apps pull components with pinned deps and style contracts.
• Components built on Radix primitives need to be shareable across projects without a published npm package per component.
• An existing shared component library should be migrated from direct file copying to registry-based distribution.
• Registry items need dependency declarations so the CLI can auto-install required npm packages alongside component files.
• A custom registry must co-exist with the upstream shadcn registry without collision.

When Not to Use

• Component authoring without registry concerns (use shadcn-component-design).
• Monorepo shared package architecture without registry distribution (use shadcn-design-system).
• CI enforcement of upstream component freshness (use shadcn-ci-integration).
• Initial project wiring and components.json setup (use shadcn-setup).

Inputs

• Component inventory: names, file paths, and peer dependencies.
• Distribution target: static URL, npm package, or monorepo local resolution.
• Consumer projects and their frameworks (Next.js App Router, Vite + React, SvelteKit).
• Whether the registry will co-exist with upstream registry.shadcn.com.
• Hosting infrastructure: GitHub Pages, Vercel, Cloudflare Pages, or private npm registry.
• Evaluation date in ISO format (YYYY-MM-DD).

Required Outputs

Depth Modes

Registry Schema Reference

registry.json — Top-Level Index

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-ui",
  "homepage": "https://ui.acme.com",
  "items": [
    {
      "name": "data-card",
      "type": "registry:component",
      "title": "Data Card",
      "description": "A card component with a header metric, trend indicator, and sparkline.",
      "files": [
        {
          "path": "registry/data-card/data-card.tsx",
          "type": "registry:component"
        }
      ],
      "dependencies": ["recharts"],
      "registryDependencies": ["card", "badge"],
      "tags": ["display", "metrics"]
    }
  ]
}

Key fields:

Registry Item Types

Per-Component Item File

Each component can have its own resolution file at registry/<name>.json (referenced by the registry index or directly via URL):

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "data-card",
  "type": "registry:component",
  "title": "Data Card",
  "description": "A card component with a header metric, trend indicator, and sparkline.",
  "files": [
    {
      "path": "registry/data-card/data-card.tsx",
      "type": "registry:component",
      "target": "components/ui/data-card.tsx"
    },
    {
      "path": "registry/data-card/use-sparkline.ts",
      "type": "registry:hook",
      "target": "hooks/use-sparkline.ts"
    }
  ],
  "dependencies": ["recharts"],
  "devDependencies": [],
  "registryDependencies": ["card", "badge"],
  "cssVars": {
    "light": {
      "--chart-trend-positive": "142 76% 36%",
      "--chart-trend-negative": "0 84% 60%"
    },
    "dark": {
      "--chart-trend-positive": "142 76% 46%",
      "--chart-trend-negative": "0 84% 70%"
    }
  },
  "tailwind": {
    "config": {}
  }
}

Key fields:

Hosting Strategies

Strategy 1: Static File Host (recommended for most teams)

Host registry.json and per-component JSON files as static files. Any static host works: GitHub Pages, Vercel, Cloudflare Pages, Netlify.

https://ui.acme.com/registry.json
https://ui.acme.com/registry/data-card.json

GitHub Pages example:

# .github/workflows/publish-registry.yml
name: Publish Registry
on:
  push:
    branches: [main]
    paths: ["registry/**"]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./registry

The registry JSON files live in registry/ in the source repo and are served from the GitHub Pages root.

Strategy 2: npm Package (for private/gated distribution)

Publish a package where registry.json and item files are included. Consumers reference the local file path or an npx-based resolver.

// package.json
{
  "name": "@acme/ui-registry",
  "version": "1.2.0",
  "files": ["registry/**"]
}

Consumer installs:

npm install --save-dev @acme/ui-registry
npx shadcn add node_modules/@acme/ui-registry/registry/data-card.json

Trade-off: Requires consumers to install the package before running the CLI. Better for gated/enterprise use.

Strategy 3: Monorepo Local Resolution

For monorepos, reference registry items by local file path directly. No hosting required.

# From an app package in the monorepo
npx shadcn add ../../packages/ui/registry/data-card.json

Or configure in components.json:

{
  "registries": {
    "acme": {
      "url": "../../packages/ui/registry"
    }
  }
}

Consumer Configuration

Add the custom registry URL to the consuming project's components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "hooks": "@/hooks",
    "lib": "@/lib"
  },
  "registries": {
    "acme": {
      "url": "https://ui.acme.com"
    }
  }
}

CLI usage with a named registry:

npx shadcn add acme/data-card

Or directly via URL (no components.json entry required):

npx shadcn add https://ui.acme.com/registry/data-card.json

Co-Existence with Upstream Registry

Custom registry items can declare registryDependencies that reference upstream shadcn components by name (e.g., "card", "badge"). The CLI resolves these from registry.shadcn.com automatically.

Collision avoidance rules:

1. Never use the same name as an upstream shadcn component in your registry unless you intentionally want to override it.
2. Use an org prefix for custom component names when collision risk exists: acme-data-card instead of data-card.
3. Custom cssVars from registry items are merged into globals.css — avoid redefining upstream token names with different values.

Versioning Strategy

The shadcn registry schema has no native version field on items. Use these conventions:

Breaking change definition for registry items:

• Removing a file from files[] — breaking
• Changing a file's target path — breaking
• Removing a cssVar that consumers may depend on — breaking
• Adding new dependencies — non-breaking (CLI installs them)
• Adding new files — non-breaking

Registry Source Repo Layout

packages/ui/
├── registry/
│   ├── registry.json              ← top-level index
│   ├── data-card/
│   │   ├── data-card.json         ← item descriptor
│   │   ├── data-card.tsx          ← component source
│   │   └── use-sparkline.ts       ← hook source
│   ├── stat-badge/
│   │   ├── stat-badge.json
│   │   └── stat-badge.tsx
│   └── ...
├── src/                           ← local usage / Storybook
│   └── components/
│       └── ui/                    ← shadcn components consumed locally
└── package.json

Relationship between registry/ and src/:

• registry/<name>/<name>.tsx is the source of truth for the component.
• src/components/ui/<name>.tsx is a symlink or build artifact used for local Storybook/testing.
• On publish, registry/*.json item files reference paths within registry/.

Pragmatic Stop Rule

Stop and deliver when:

1. registry.json is valid against the schema and all items resolve.
2. Each component item file has files, dependencies, registryDependencies, and cssVars fully declared.
3. npx shadcn add <url> installs the component, its deps, and CSS vars correctly in a test consumer project.
4. Co-existence with upstream registry is verified — no name collisions, no CSS variable conflicts.
5. Versioning strategy is documented and the first version is tagged.
6. Consumer onboarding instructions (one components.json edit + one CLI command) are written.