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 generated registry JSON 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/**`
`registry:style`	Style-level CSS and dependency metadata	`registry/items/styles/**`
`registry:theme`	Theme CSS variables	`registry/items/themes/**`
`registry:font`	Font metadata	`registry/items/fonts/**`
`registry:base`	Design system base configuration	`registry/items/bases/**`
`registry:item`	Universal or metadata-only items	`registry/items/items/**`

The scaffold creates each item in its own folder:

registry/items/components/example-card/
  _registry.mdx
  _preview.tsx
  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:ui --name prompt-input --description "An AI prompt input." --target @ui/ai/prompt-input.tsx
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
bun --bun ./scripts/new.ts --type registry:font --name font-inter --description "Inter font metadata." --font-family "'Inter Variable', sans-serif" --font-import Inter --font-variable=--font-sans

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; optional for source-backed items that need a custom install path, including shadcn target placeholders like @ui/ai/prompt-input.tsx.
--file-extension: for registry:file and targeted registry:item; defaults to ts.
--font-family, --font-import, --font-variable: required for noninteractive registry:font scaffolds.

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

Authoring

Use _registry.mdx for public metadata and usage docs. Put the optional named Preview export in _preview.tsx. Keep both files private to authoring; never list them 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. Metadata-only styles, themes, fonts, bases, and universal items can omit files.

List authored source files with paths relative to the item _registry.mdx file. The catalog automatically emits files[].target placeholders such as @ui/<name>.tsx, @components/<name>.tsx, @hooks/<name>.ts, and @lib/<name>.ts for file types that should install through the user's components.json aliases. Use explicit target values for registry:page, registry:file, and nested alias installs like @ui/ai/prompt-input.tsx; do not add registry/items/** prefixes or a separate sourcePath field.

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.