Registry

Registry items live under registry/items/<section>/<name>/. <section> is components, blocks, utilities, or files. Each item is a folder with an _registry.svx metadata file, a live preview, and a Storybook story. There’s no scaffold CLI yet — copy an existing item folder as a starting point (registry/items/components/button is a good one) and adjust it.

Item layout

1registry/items/components/badge/
2  _registry.svx
3  _preview.svelte
4  stories/badge.stories.ts
5
6registry/items/files/styles/
7  _registry.svx
8  _preview.svelte
9  stories/styles.stories.svelte
10  globals.css
11  theme.css
12  theme-secondary.css
13  theme-tertiary.css

• _registry.svx — YAML frontmatter (name, type, files, dependencies) plus optional Markdown usage docs, rendered on the item’s docs page
• _preview.svelte — live demo shown in the “Preview” tab (never published in the item JSON)
• stories/*.stories.svelte — the matching Storybook story

Where the source lives

Every registry item’s source lives inside its own item folder, under registry/items/<section>/<name>/. src/lib/components/** is the documentation site’s own application shell — it is never where a registry item’s .svelte/.ts source lives, even for components (button, badge, card, accordion, tabs, avatar, breadcrumb, …) that also happen to render the docs site’s own UI. The docs site consumes those the same way an external consumer would after installing them — import via the $registry alias ($registry/items/components/<name>/index.js), never by re-implementing the component under src/lib/components/ui/. See the registry-source-boundary agent skill (.agents/skills/registry-source-boundary/SKILL.md) for the full rationale and how to catch a drifted duplicate.

files[].path in _registry.svx points to the real on-disk source file:

• Components, blocks, and utilities authored for this registry (button, badge, card, accordion, tabs, avatar, hero, cn, …) keep their source directly in the item folder (or src/lib/utils.ts for cn).
• Published CSS and other standalone files (styles) keep _registry.svx, _preview.svelte, and the CSS together under registry/items/files/<name>/. They still appear in the Utilities catalog (for example /utilities/styles).

1files:
2  - path: registry/items/components/button/button.svelte
3    type: registry:ui
4    target: "~/components/button/button.svelte"

CSS-only items are authored in that same files/ folder:

1files:
2  - path: registry/items/files/styles/globals.css
3    type: registry:file
4    target: "~/styles/globals.css"

target is where the file lands in a consumer’s project when installed via the CLI. Prefix with ~/ for a path from the project root. Without it, registry:ui files resolve under the ui alias (src/lib/components/ui) and registry:style CSS files nest under the Tailwind CSS filename from components.json.

Generating and validating

1bun run registry:generate   # writes registry.generated.json from registry/items/**
2bun run registry:build      # generate, then build static/r/*.json via `shadcn-svelte registry build`
3bun run registry:doctor     # lint _registry.svx files: bad frontmatter, missing files[], orphan folders

Run registry:doctor after adding or editing an item — it catches the mistakes registry:generate doesn’t, like a files[].path that doesn’t exist or a folder placed under the wrong section (registry/items/<section>/ must be components, blocks, utilities, or files, or the item is silently invisible to the catalog).