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