Colorful 3D geometric shapes

How to Create Your Own Shadcn/UI Component Registry

Derrick Nuby — Software Engineer
August 16, 2025•7 minutes

Shadcn/ui has revolutionized how developers think about UI components. Unlike traditional component libraries that come as black-box npm packages, shadcn/ui provides beautiful, accessible components that you actually own. When you install a shadcn component, the code lands directly in your project - fully customizable, no dependencies to worry about, no version conflicts.

But here's what makes shadcn truly powerful: the registry system. This innovative approach lets you distribute components without the traditional npm packaging friction. Instead of installing packages, you pull components directly into your codebase where you have complete control.

The benefits are game-changing:

🎯Full Ownership

Components become part of your codebase. Customize, modify, and extend them however you need.

📦No Dependencies

No more dependency hell. No version conflicts. Just clean code in your project.

⚡Easy Distribution

Share components with a simple URL. No npm publishing, no complex setup.

🔧Perfect for Teams

Maintain consistency across projects while allowing customization.

Ready to create your own component registry? In this guide, I'll show you how to build a registry that others can install with a simple npx shadcn add command - just like the official shadcn/ui components.

What We're Building

By the end of this tutorial, you'll have:

✓Your own component registry hosted online
✓A reusable OrganisationUnitTree component
✓The ability for others to install your components with:
bash
npx shadcn add https://ui.derrick.rw/r/organisation-unit-tree.json

Prerequisites

•Node.js 18+ installed
•Basic knowledge of React and TypeScript
•A GitHub account (for hosting)

Step 1: Initialize Your Next.js Project

First, let's create a new Next.js project with shadcn/ui:

Next.js Installation Initialize Shadcn

Step 2: Install Required Components

Install the base components we'll need:

bash
npx shadcn@latest add input button badge card

Step 3: Create the Registry Structure

Create the required folder structure:

bash
# Create registry directories
mkdir -p registry/default/ui

Your project structure should now look like:

bash
my-component-registry/
├── registry/
│   └── default/
│       └── ui/
├── public/
│   └── r/ (this is auto generated)
├── src/
│   └── components/
│       └── ui/
└── registry.json (we'll create this)

Step 4: Create Your Component

Create the OrganisationUnitTree component:

bash
# Create the component file
touch registry/default/ui/organisation-unit-tree.tsx

Add the following code to registry/default/ui/organisation-unit-tree.tsx:

typescript
"use client"

import type React from "react"

import { useCallback, useEffect, useState, useMemo } from "react"
import { Input } from "@/components/ui/input"
import { Badge } from "@/components/ui/badge"
import { Card, CardContent } from "@/components/ui/card"
import { Button } from "@/components/ui/button"
import { Loader2, Search, Users, ChevronDown, ChevronRight, X } from 'lucide-react'
import { cn } from "@/lib/utils"

// ... continue the component

Step 5: Create Registry Configuration

Create registry.json in your project root:

json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "my-component-registry",
  "homepage": "https://ui.derrick.rw",
  "items": [
    {
      "name": "organisation-unit-tree",
      "type": "registry:ui",
      "title": "Organisation Unit Tree",
      "description": "A tree component for selecting organisation units with lazy loading support",
      "files": [
        {
          "path": "registry/default/ui/organisation-unit-tree.tsx",
          "type": "registry:ui"
        }
      ],
      "dependencies": ["lucide-react"],
      "registryDependencies": ["input", "button", "badge", "card"]
    }
  ]
}

Step 6: Build the Registry

Run the shadcn build command to generate the registry files:

bash
npx shadcn build

This creates JSON files in the public/r/ directory that can be consumed by the shadcn CLI.

Step 7: Deploy Your Registry

Deploy your project to Vercel (or your preferred hosting):

bash
https://your-domain.vercel.app/r/organisation-unit-tree.json

Step 8: Test Installation from Your Registry

Now anyone can install your component:

bash
npx shadcn@latest add https://your-domain.vercel.app/r/organisation-unit-tree.json

Advanced Features

Adding Multiple Components

To add more components to your registry, simply:

1.Create new component files in registry/default/ui/
2.Add new items to your registry.json
3.Run npx shadcn build again

v0.dev Integration

Create a link to open your component in v0.dev:

bash
https://v0.dev?registry=https://your-domain.vercel.app/r/organisation-unit-tree.json

Conclusion

You now have your own component registry! Users can install your components with a simple command, and you can iterate and improve them over time.

Key benefits:

✅Easy distribution of custom components
✅Automatic dependency management
✅Version control through git
✅Community can contribute via pull requests

The OrganisationUnitTree component we built includes:

•Search functionality
•Single/multi selection
•Lazy loading support
•Level restrictions
•Keyboard navigation
•Responsive design

Start building your component library today and share it with the world!

Resources

Shadcn/UI Documentation Component Registry Schema Example Registry Source