registry.json

Core Idea

Schema for the entry point of any custom registry: declares registry metadata (name, homepage) and lists (or composes via include) all installable items. JSON Schema: https://ui.shadcn.com/schema/registry.json.

Key Concepts

• $schema: Points to https://ui.shadcn.com/schema/registry.json for tooling/validation.
• name: Registry name, used for data attributes/metadata; required on the root file.
• homepage: Registry's homepage URL; required on the root file.
• include: Composes a registry from multiple registry.json files (relative paths to explicit files, no folder shorthand). Included files may omit name/homepage. Item names must be globally unique across the resolved (flattened) registry.
• items: Array of registry items, each conforming to the registry-item schema. Root registry.json must define at least one of items or include; items defaults to [] if omitted.
• GitHub repos use the same format: A public GitHub repo becomes a registry simply by having registry.json at its root; the CLI resolves include and installs directly from the repo.
• Path resolution with include: file paths inside an included registry.json are relative to that file's location, not the root. shadcn build flattens everything and strips include from the output.

Code Examples

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "shadcn",
  "homepage": "https://ui.shadcn.com",
  "items": [
    {
      "name": "hello-world",
      "type": "registry:block",
      "title": "Hello World",
      "description": "A simple hello world component.",
      "registryDependencies": ["button", "@acme/input-form", "https://example.com/r/foo"],
      "dependencies": ["is-even@3.0.0", "motion"],
      "files": [{ "path": "registry/default/hello-world/hello-world.tsx", "type": "registry:component" }]
    }
  ]
}

• O que demonstra: registry.json completo com um item que mistura registryDependencies local, namespace e URL remota.

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "include": ["components/ui/registry.json", "hooks/registry.json"]
}

• O que demonstra: registry raiz composto a partir de dois arquivos filhos, sem items diretos.

Reference Tables

Field	Type	Required	Notes
$schema	string	recommended	schema URL for validation
name	string	root only	registry identifier
homepage	string	root only	registry homepage URL
include	string[]	no	paths to nested registry.json files to compose
items	RegistryItem[]	conditional	required unless include is used; defaults to []

Anti-patterns

• Using include with folder paths instead of explicit files: folder shorthand is not supported; each include entry must point to a specific registry.json.
• Duplicate item names across included files: names must be unique across the entire resolved registry, not just per file.
• Expecting generated (built) output to retain include: shadcn build always flattens; the published registry.json never contains include.

Key Takeaways

1. Two structuring options: single flat registry.json (simple registries) vs. root + include composition (large registries split by domain, e.g. components/ui/registry.json, hooks/registry.json).
2. A public GitHub repo IS a registry the moment it has a root registry.json — no separate hosting needed.
3. Path resolution is context-sensitive: relative to the declaring file when using include, relative to project root in a single-file registry.

Connects To

• registry-item-json (ch108): schema every entry in items must satisfy.
• registry-getting-started (ch099): practical guide building on this schema (single vs. include structuring, build/serve steps).
• registry-registry-index (ch105): directory submission requires a flat (non-include) resolved output.