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
.claude/rules/registry.mdWhat 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-cardregistry JSON and find missing metadata fields. - Write the publication steps using
vercel.jsonandvercel --prod.
How to install registry
Manually: put the files in place
.claude/rules/registry.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/registry.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/registry.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/registry.mdManually: put the files in place
.clinerules/registry.mdStep 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