Registry |

Registry items live under registry/items/** and can be installed by shadcn-compatible CLIs. Start new items with the scaffold command so the folder, _registry.mdx, source file, metadata, and install paths follow the template conventions.

bun --bun ./scripts/new.ts --type registry:ui --name example-card --description "A compact card component."

Or, run the command without flags if you want an interactive prompt (recommended).

bun --bun ./scripts/new.ts

Requires Bun

Make sure Bun is installed before running these scripts.

Item Types

Choose the registry type from what the item installs:

Type	Use For	Folder
`registry:ui`	Shadcn-style UI components	`registry/items/components/**`
`registry:component`	Components outside `components/ui`	`registry/items/components/**`
`registry:block`	Larger composed UI patterns	`registry/items/blocks/**`
`registry:hook`	React hooks	`registry/items/hooks/**`
`registry:lib`	Utility or helper modules	`registry/items/lib/**`
`registry:page`	App page files with explicit targets	`registry/items/pages/**`
`registry:file`	Other files with explicit install targets	`registry/items/files/**`

The scaffold creates each item in its own folder:

registry/items/components/example-card/
  _registry.mdx
  example-card.tsx

CLI Flags

Use flags for agent-friendly and CI-friendly scaffolding:

bun --bun ./scripts/new.ts --type registry:block --name stats-panel --description "A metrics panel with reusable sample data."
bun --bun ./scripts/new.ts --type registry:page --name dashboard-page --description "A starter dashboard page." --target app/dashboard/page.tsx
bun --bun ./scripts/new.ts --type registry:file --name chart-theme --description "Shared chart theme tokens." --target styles/chart-theme.css --file-extension css

Supported flags:

--type: registry item type. Defaults to registry:ui.
--name: required kebab-case item name.
--title: optional public title. Defaults from the name.
--description: required public description.
--target: required for registry:page and registry:file.
--file-extension: only for registry:file; defaults to ts.

Use bun --bun ./scripts/new.ts --help to print the full usage.

Authoring

Use _registry.mdx for public metadata, usage docs, and the named Preview export. Keep _registry.mdx private to authoring; never list it in files.

For one-file registry:ui items, the catalog infers <item-name>.tsx. Hooks, libs, blocks, pages, target paths, and multi-file items should list files explicitly.

Use localRegistryDependencies for dependencies on other local registry items.

After editing an item, run vp check --fix on touched files and bun --bun ./scripts/doctor.ts. Run vp build when registry docs, routes, JSON output, catalog loading, or source loading changed.