--- title: Getting Started description: Learn how to get setup and run your own component registry. --- This guide will walk you through the process of setting up your own registry. It assumes you already have a project with components, hooks, utilities or other files you would like to distribute. **If you have an existing public GitHub repository, you can turn it into a registry by adding a `registry.json` file at the root.** See [GitHub Registries](/docs/registry/github) for details. If you're starting a new registry project, you can use the [registry template](https://github.com/shadcn-ui/registry-template) as a starting point. We have already configured it for you. ## Requirements You are free to design and publish your custom registry as you see fit. The only requirement is that your registry catalog and registry items must conform to the [registry schema specification](/docs/registry/registry-json) and [registry-item schema specification](/docs/registry/registry-item-json). Your registry can be a Next.js, Vite, Vue, Svelte, PHP or any other framework as long as it supports serving JSON over HTTP. It can also be a public GitHub repository with a `registry.json` file at the root. If you'd like to see an example of a registry, we have a [template project](https://github.com/shadcn-ui/registry-template) for you to use as a starting point. ## registry.json The `registry.json` is the entry point for the registry. It contains the registry's name, homepage, and defines all the items present in the registry. Your registry must have this file (or JSON payload) present at the root of the registry endpoint. The registry endpoint is the URL where your registry is hosted. Here's an example `registry.json` file: ```json title="registry.json" showLineNumbers { "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "acme", "homepage": "https://acme.com", "items": [ { "name": "button", "type": "registry:ui", "title": "Button", "description": "A simple button component.", "files": [ { "path": "components/ui/button.tsx", "type": "registry:ui" } ] } ] } ``` ## Structure your registry You can structure your source registry in one of two ways: - Define all items in a single root `registry.json`. - Use a root `registry.json` with `include` to compose multiple `registry.json` files. ### Option A: Single registry.json Create a `registry.json` file in the root of your project. Add all your registry items to the `items` array. This is the simplest way to define a registry. ```json title="registry.json" showLineNumbers { "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "acme", "homepage": "https://acme.com", "items": [ { "name": "button", "type": "registry:ui", "title": "Button", "description": "A simple button component.", "files": [ { "path": "components/ui/button.tsx", "type": "registry:ui" } ] }, { "name": "hello-world", "type": "registry:block", "title": "Hello World", "description": "A simple hello world component.", "registryDependencies": ["button"], "files": [ { "path": "registry/default/hello-world/hello-world.tsx", "type": "registry:component" } ] } ] } ``` This `registry.json` file must conform to the [registry schema specification](/docs/registry/registry-json). ### Option B: Using include For larger registries, you can use `include` to compose your source registry from multiple `registry.json` files. ```txt registry.json components └── ui ├── button.tsx ├── input.tsx └── registry.json hooks ├── registry.json ├── use-media-query.ts └── use-toggle.ts ``` The root `registry.json` defines the registry metadata and includes the nested registry files. {/* prettier-ignore */} ```json title="registry.json" showLineNumbers { "$schema": "https://ui.shadcn.com/schema/registry.json", "name": "acme", "homepage": "https://acme.com", "include": [ "components/ui/registry.json", "hooks/registry.json" ] } ``` Included `registry.json` files are valid registry files for composition and may omit `name` and `homepage`. Only the root `registry.json` must define the registry metadata. ```json title="components/ui/registry.json" showLineNumbers { "$schema": "https://ui.shadcn.com/schema/registry.json", "items": [ { "name": "button", "type": "registry:ui", "files": [ { "path": "button.tsx", "type": "registry:ui" } ] }, { "name": "input", "type": "registry:ui", "files": [ { "path": "input.tsx", "type": "registry:ui" } ] } ] } ``` ```json title="hooks/registry.json" showLineNumbers { "$schema": "https://ui.shadcn.com/schema/registry.json", "items": [ { "name": "use-toggle", "type": "registry:hook", "files": [ { "path": "use-toggle.ts", "type": "registry:hook" } ] }, { "name": "use-media-query", "type": "registry:hook", "files": [ { "path": "use-media-query.ts", "type": "registry:hook" } ] } ] } ``` When using `include`, file paths are relative to the `registry.json` file that declares the item. ## Add an item ### Create a UI component Add your first item. Here's an example of a simple `