create-shadcn-registry

A CLI tool that scaffolds a custom shadcn/ui component registry. Run your own registry to distribute custom components, hooks, and blocks to any React project via the shadcn CLI.

How It Works

1. Scaffolding — Clones the registry-template and customizes it with your settings.

2. Registry Definition — The template uses registry.json to define components and their files. Each entry maps a component name to its source path and dependencies.

3. Build & Serve — The built registry serves static JSON files (e.g. public/r/button.json) that the shadcn CLI fetches when installing components.

4. Distribution — Once deployed, consumers add your registry URL to components.json and run shadcn add @your-registry/button to install components.

Prerequisites

• Node.js 18+
• Git (used to clone the registry template)

Installation

# Using npm
npx create-shadcn-registry

# Using bun (recommended)
bunx create-shadcn-registry

Usage

Run the CLI and follow the prompts:

npx create-shadcn-registry

You'll be asked for:

| Prompt | Description | Example | |--------|-------------|---------| | Registry name | Identifier for your registry (used as @name/component) | my-ui | | Project location | Folder to create the registry in | . or ./my-registry | | Style | Shadcn/UI style variant (Only ShadCN/ui defaults supported) | New York or Default | | Homepage | URL where the registry will be hosted | https://example.com |

The tool clones the template, applies your choices, and writes a ready-to-use registry.

Flags (skip prompts)

Pass any flag to skip that prompt. Mix flags and prompts as needed:

# Fully automated
npx create-shadcn-registry --registry-name my-ui --project-location ./registry --style default --homepage https://my-registry.com

# Only specify some and prompt for the rest
npx create-shadcn-registry --registry-name my-ui --style default

| Flag | Description | |------|-------------| | --registry-name | Registry identifier (e.g. @name/component) | | --project-location | Folder to create the registry in | | --style | new-york or default | | --homepage | URL where the registry will be hosted |

Project Structure

After creation, you'll have:

your-registry/
├── app/
│   └── page.tsx          # Demo page using registry components
├── registry/
│   ├── new-york/         # Or "default" — component source files
│   │   └── ui/
│   │       └── button.tsx
│   └── ...
├── registry.json         # Registry manifest (components, deps, files)
├── package.json
└── ...

Next Steps

1. Add components, hooks, and blocks — Use add-component, add-hook, or add-block, or edit registry.json and add files under registry/<style>/.
2. Build — Run npm run registry:build (or equivalent) to compile the registry.
3. Local testing — Use the create-test-app command (see below).
4. Deploy — Host the built public/r/ output where your homepage URL points.

Full details: shadcn Registry Docs

Scripts

| Command | Description | |---------|-------------| | bun start | Run the create-shadcn-registry CLI | | bun run add-component | Add a new component to an existing registry | | bun run add-hook | Add a new hook to an existing registry | | bun run add-block | Add a new block to an existing registry | | bun run remove-component | Remove a component from the registry | | bun run remove-hook | Remove a hook from the registry | | bun run remove-block | Remove a block from the registry | | bun run create-test-app | Create a test Next.js app and add registry components |

add-component

From a registry project (or with the registry folder path), run:

npx create-shadcn-registry add-component
# or
bun run add-component

You'll be prompted for:

• Registry folder — Path to the folder containing registry.json
• Component name — kebab-case (e.g. my-component)
• Style — New York or Default

The command creates an example component file and updates registry.json.

Pass flags to skip prompts:

npx create-shadcn-registry add-component --component-name my-component --registry-folder . --style new-york

| Flag | Description | |------|-------------| | --component-name | kebab-case component name | | --registry-folder | Path to registry (default: .) | | --style | new-york or default | | --dependencies | Comma-separated npm packages (merged with defaults: class-variance-authority) |

add-hook

Add a standalone React hook to your registry:

npx create-shadcn-registry add-hook
# or
bun run add-hook

You'll be prompted for:

• Registry folder — Path to the folder containing registry.json
• Hook name — Use use-<name> format (e.g. use-my-hook)
• Style — New York or Default

The command creates a hook file at registry/<style>/hooks/<hook-name>.ts and updates registry.json.

Pass flags to skip prompts:

npx create-shadcn-registry add-hook --hook-name use-my-hook --registry-folder . --style new-york

| Flag | Description | |------|-------------| | --hook-name | Hook name in use- format | | --registry-folder | Path to registry (default: .) | | --style | new-york or default | | --dependencies | Comma-separated npm packages |

add-block

Add a block (complex component with multiple files) to your registry:

npx create-shadcn-registry add-block
# or
bun run add-block

You'll be prompted for:

• Registry folder — Path to the folder containing registry.json
• Block name — kebab-case (e.g. my-block)
• Style — New York or Default

The command creates a block folder at registry/<style>/blocks/<block-name>/ with a component and hook file, and updates registry.json.

Pass flags to skip prompts:

npx create-shadcn-registry add-block --block-name my-block --registry-folder . --style new-york

| Flag | Description | |------|-------------| | --block-name | kebab-case block name | | --registry-folder | Path to registry (default: .) | | --style | new-york or default | | --dependencies | Comma-separated npm packages |

remove-component

Remove a UI component from your registry:

npx create-shadcn-registry remove-component
# or
bun run remove-component

You'll be prompted for:

• Registry folder — Path to the folder containing registry.json
• Component to remove — Select from existing components

The command deletes the component file(s) and updates registry.json.

Pass flags to skip prompts:

npx create-shadcn-registry remove-component --component button --registry-folder .

| Flag | Description | |------|-------------| | --component | Component name to remove | | --registry-folder | Path to registry (default: .) |

remove-hook

Remove a hook from your registry:

npx create-shadcn-registry remove-hook
# or
bun run remove-hook

You'll be prompted for:

• Registry folder — Path to the folder containing registry.json
• Hook to remove — Select from existing hooks

Pass flags to skip prompts:

npx create-shadcn-registry remove-hook --hook use-my-hook --registry-folder .

| Flag | Description | |------|-------------| | --hook | Hook name to remove | | --registry-folder | Path to registry (default: .) |

remove-block

Remove a block from your registry:

npx create-shadcn-registry remove-block
# or
bun run remove-block

You'll be prompted for:

• Registry folder — Path to the folder containing registry.json
• Block to remove — Select from existing blocks

Pass flags to skip prompts:

npx create-shadcn-registry remove-block --block my-block --registry-folder .

| Flag | Description | |------|-------------| | --block | Block name to remove | | --registry-folder | Path to registry (default: .) |

create-test-app

The create-test-app command validates the full flow:

1. Build your registry
2. Start a local registry server (tries port 3000, then 3001, 3002, etc. if taken)
3. Create a new Next.js app
4. Initialize shadcn and point it at your registry
5. Add registry components to the app
6. Stop the registry server

npx create-shadcn-registry create-test-app
# or
bun run create-test-app

You'll be prompted for the registry folder (with registry.json) and the target app folder (must be empty).

Pass flags to skip prompts:

npx create-shadcn-registry create-test-app --registry-folder ./test --app-folder ./test-app --package-manager bun

| Flag | Description | |------|-------------| | --registry-folder | Path to registry | | --app-folder | Folder to create the Next app in | | --package-manager | npm, pnpm, or bun |

License

MIT