FAQ (Registry)

Core Idea

Short answers to recurring registry-authoring questions: complex component anatomy, adding Tailwind colors/theme vars, and how registryDependencies resolves bare names vs. GitHub addresses.

Key Concepts

• Complex component: A registry:block combining a registry:page (with target), multiple registry:component/registry:hook/registry:lib files, and a registry:file config with target: "~/hello.config.ts".
• New Tailwind color: Add to cssVars.light and cssVars.dark (e.g. brand-background, brand-accent); the CLI updates the project's CSS file and the color becomes usable as bg-brand/text-brand-accent.
• New/override theme variable: Add to cssVars.theme (e.g. text-base, ease-in-out, font-heading).
• Bare registryDependencies names: "button" always means the built-in shadcn button, never same-repo GitHub items — use the full GitHub address (acme/ui/button) for that.
• Pinning a GitHub item: append #ref (branch, tag, or full commit SHA) — npx shadcn@latest add acme/ui/button#v1.2.0. Prefer tags/SHAs for published registries.
• Private GitHub repos not supported: GitHub registry addresses only work with public github.com repos; use an authenticated namespace URL instead.

Code Examples

{
  "cssVars": {
    "light": { "brand-background": "oklch(0.205 0.015 18)", "brand-accent": "oklch(0.205 0.015 18)" },
    "dark": { "brand-background": "oklch(0.205 0.015 18)", "brand-accent": "oklch(0.205 0.015 18)" }
  }
}

• O que demonstra: adicionar uma cor Tailwind nova via cssVars.light/dark de um registry item.

Anti-patterns

• Expecting button in registryDependencies to mean "the button in my GitHub repo": it always resolves to the built-in shadcn item; use acme/ui/button for repo-local items.

Key Takeaways

1. New colors go in cssVars.light/dark; new/overridden theme scale values (spacing, fonts, easing) go in cssVars.theme.
2. GitHub item pinning uses #ref syntax; commit SHA is safest for reproducibility.
3. Private-repo GitHub registry addresses are unsupported today — namespace + auth headers is the workaround.

Connects To

• registry-item-json (ch108): full cssVars and registryDependencies field spec.
• registry-authentication (ch102): the namespace+auth workaround for private repos.