Skip to main content
rule CX Codex

registry — Claude Code rule: what it does, how to install

registry is a Claude Code rule for publishing UI components as source code. It defines registry metadata and a deployment flow.

Apache-2.0 ★ 141 updated 2026-11-17

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/registry.md
Open on GitHub

What registry does

The registry rule explains a source-based component registry instead of a compiled package. It contrasts registry distribution with npm, shows local component imports, and defines JSON fields for dependencies, registry dependencies, files, and category.

The publishing flow uses a component directory with JSON under public/, headers in vercel.json, and vercel --prod. A component is added through npx shadcn@latest add with the JSON address. A registry entry without dependencies, linked registry components, files, or a category is incomplete.

What it helps with

  • compare source-based registries with npm packages
  • define metadata for a UI component registry
  • configure JSON headers in vercel.json
  • publish a registry with vercel --prod
  • add a component through the shadcn CLI

Example prompts for the agent

  • Explain how a source registry differs from npm for UI components.
  • Review the metric-card registry JSON and find missing metadata fields.
  • Write the publication steps using vercel.json and vercel --prod.

How to install registry

Manually: put the files in place

.claude/rules/registry.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about registry

How do I install registry in Claude Code?

Place the rule file at .claude/rules/registry.md.

What does registry do?

The rule describes distributing components as source code. It covers registry JSON metadata, deployment through Vercel, and component installation with npx shadcn@latest add.

Which fields belong in a component registry JSON file?

The entry uses name, type, description, dependencies, registryDependencies, files, and category. Each file record includes its type, path, and content.

Source text

registry.md · Apache-2.0
---
title: Component Registries
impact: LOW
impactDescription: Source code distribution
tags: registry, shadcn, distribution, cli, source-code
---

## Component Registries

Registries distribute **source code**, not compiled packages. This enables true component ownership and customization.

### Core Concept

**Bad:**

```typescript
// Traditional npm - compiled dependency
import { Button } from "some-ui-library";
```

**Good:**

```typescript
// Registry-based - source code in your project
import { Button } from "@/components/ui/button";
```

### Registry Metadata Format

**Bad:**

```json
{
  "name": "announcement",
  "type": "registry:component",
  "description": "A compound badge component"
  // Missing dependencies, registryDependencies, files, and category
}
```

**Good:**

```json
{
  "name": "announcement",
  "type": "registry:component",
  "description": "A compound badge component",
  "dependencies": ["class-variance-authority", "lucide-react"],
  "registryDependencies": ["badge"],
  "files": [
    {
      "type": "registry:component",
      "path": "announcement.tsx",
      "content": "..."
    }
  ],
  "category": "ui"
}
```

### Quick Publishing

**1. Create structure:**

```
my-component/
├── public/
│   └── metric-card.json
└── vercel.json
```

**2. Configure headers (`vercel.json`):**

**Example:**

```json
{
  "headers": [
    {
      "source": "/(.*).json",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Content-Type", "value": "application/json" }
      ]
    }
  ]
}
```

**3. Deploy:**

**Example:**

```bash
vercel --prod
```

**4. Users install via:**

**Example:**

```bash
npx shadcn@latest add https://your-project.vercel.app/metric-card.json
```

### Component JSON Structure

**Example:**

```json
{
  "name": "metric-card",
  "type": "registry:component",
  "description": "Display metrics with icon and trend",
  "dependencies": ["lucide-react"],
  "registryDependencies": ["card"],
  "files": [
    {
      "type": "registry:component",
      "path": "metric-card.tsx",
      "content": "import { Card } from '@/components/ui/card'\n\nexport function MetricCard({ title, value }) {\n  return <Card><h3>{title}</h3><p>{value}</p></Card>\n}"
    }
  ],
  "category": "ui"
}
```

### Registry vs npm

| Aspect        | Registry          | npm             |
| ------------- | ----------------- | --------------- |
| Distribution  | Source code       | Compiled        |
| Ownership     | Full control      | Dependency lock |
| Customization | Modify freely     | Fork/override   |
| Updates       | Manual copy       | `npm update`    |
| Bundle size   | Only what you use | Full package    |

### Best Practices

**For Authors:**

1. Document dependencies
2. Version components
3. Provide examples
4. Test compatibility
5. Use semantic naming

**For Consumers:**

1. Review source code
2. Check dependencies
3. Customize freely
4. Track updates
5. Test thoroughly

### When to Use

**Use registries when:**

- Sharing with community
- Users need source ownership
- Building for specific frameworks
- Quick distribution needed

**Use npm when:**

- Distributing compiled code
- Need version management
- Framework-agnostic libraries
- Complex build processes

© maxtrigify · Apache-2.0 · maxtrigify/Otto

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set18

The whole set →
npm npm is a Claude Code rule that guides the packaging of UI components into versioned releases. It enforces strict exports mapping, peer dependency boundaries, and build steps. CX Codex +1 ★ 141repo stars marketplaces The marketplaces rule for Claude Code organizes component discovery and integration from external registries. It helps the agent evaluate code quality before adding dependencies. CX Codex +1 ★ 141repo stars design-tokens design-tokens is a Claude Code rule that replaces hardcoded colors with semantic tokens. Light and dark themes then change variable values instead of component classes. CX Codex +1 ★ 141repo stars composition The composition rule for Claude Code guides the breakdown of complex UI components into small, focused parts. It serves when building component libraries or flexible interfaces. CX Codex +1 ★ 141repo stars overview overview is a Claude Code rule for designing accessible, composable UI components. It comes into play while shaping component APIs and shared patterns. CX Codex +1 ★ 141repo stars types The types rule for Claude Code standardizes component prop definitions in TypeScript. It provides a framework for building flexible, type-safe interfaces across React projects. CX Codex +1 ★ 141repo stars data-attributes data-attributes is a Claude Code rule for styling component states and targeting nested parts with data-state and data-slot. CX Codex +1 ★ 141repo stars principles The principles rule for Claude Code establishes six core standards for component design. It guides agents during component creation, refactoring, and evaluation. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open