Shadcn Registry Reference

Quick reference for the shadcn/ui registry system - key concepts, workflows, and configuration.

This page serves as a quick refresher for the shadcn registry system. For complete documentation, visit the official shadcn registry docs.

What is a Registry?

A registry is a distribution system for code. It allows you to share components, hooks, pages, config files, and other code with any project using the shadcn CLI.

The registry works with any project type and any framework — not limited to React.

Key Files

registry.json

The entry point for your registry. Lists all items and metadata.

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "evolphin",
  "homepage": "https://evolphin.com",
  "items": [
    // Your registry items
  ]
}

Field	Description
`name`	Registry namespace (e.g., `evolphin`, `acme`)
`homepage`	Your registry's homepage URL
`items`	Array of registry item definitions

Registry Item Types

Each item in your registry has a type that determines how it's resolved:

Type	Description	Target Path
`registry:ui`	UI components	`components/ui/`
`registry:component`	General components	`components/`
`registry:block`	Full-page blocks/templates	`components/`
`registry:hook`	React hooks	`hooks/`
`registry:lib`	Utility libraries	`lib/`
`registry:page`	Full pages	`app/` or `pages/`
`registry:file`	Arbitrary files	Custom path
`registry:theme`	Theme configurations	Styles
`registry:style`	Style variants (e.g., `new-york`)	-

Registry Item Schema

Each item in registry.json follows this structure:

{
  "name": "hello-world",
  "type": "registry:block",
  "title": "Hello World",
  "description": "A simple hello world component.",
  "files": [
    {
      "path": "registry/default/hello-world/hello-world.tsx",
      "type": "registry:component"
    }
  ],
  "dependencies": ["lucide-react"],
  "registryDependencies": ["button"]
}

Key Properties

Property	Required	Description
`name`	✅	Unique identifier for the item
`type`	✅	Item type (see table above)
`title`	❌	Human-readable title
`description`	❌	Detailed description
`files`	✅	Array of files to include
`dependencies`	❌	npm packages required
`registryDependencies`	❌	Other registry items required

Dependencies vs Registry Dependencies

`dependencies`

npm packages that will be installed:

{
  "dependencies": ["@radix-ui/react-accordion", "zod", "lucide-react@0.400.0"]
}

`registryDependencies`

Other registry items that will be added:

{
  "registryDependencies": [
    "button", // shadcn/ui component
    "@acme/input-form", // namespaced component
    "https://example.com/r/editor.json" // remote URL
  ]
}

Building Your Registry

1. Install CLI

bash pnpm add shadcn@latest

bash npm add shadcn@latest

bash yarn add shadcn@latest

2. Add Build Script

{
  "scripts": {
    "registry:build": "shadcn build"
  }
}

3. Run Build

bash pnpm registry:build

bash npm run registry:build

bash yarn registry:build

Output goes to public/r/ by default (e.g., public/r/hello-world.json).

Installing from Registry

Users can add items from your registry using:

npx shadcn@latest add https://your-registry.com/r/hello-world.json

Or with namespaces configured:

npx shadcn@latest add @evolphin/hello-world

Our Setup

In Evolphin UI, our registry is located at:

registry/
└── default/
    └── ui/
        ├── button.tsx
        ├── card.tsx
        ├── dialog.tsx
        └── ...

We use the default style variant and components are available via:

import { Button } from "@/registry/default/ui/button";

Quick Reference Links

Official Docs

Complete shadcn registry documentation

Getting Started

Step-by-step setup guide

registry.json Schema

Full registry.json specification

registry-item.json Schema

Full item schema specification

Examples

Registry configuration examples

Authentication

Secure your registry

Search