shadcn-core-registry

name	shadcn-core-registry
description	Use when authoring or consuming a shadcn registry, when configuring the `registries` field in components.json, when wiring a private or paid component library behind a namespace prefix like `@myorg/datepicker`, when securing a custom registry with bearer tokens or API keys, when hosting a `registry.json` plus per-item JSON files, or when explaining why the `style`, `baseColor`, or `cssVariables` fields cannot be changed after `init`. Prevents the missing-`{name}`-placeholder trap that breaks every namespace install, the committed-secret leak from inlining an API key instead of using `${ENV_VAR}` expansion, the alias-mismatch silent failure from setting `aliases.components` to one path while imports reference another, the immutable-field surprise from editing `style`/`baseColor`/`cssVariables` post-init, and the Tailwind v3-vs-v4 config-shape confusion. Covers every components.json field in depth (purpose, constraints, defaults, immutability), the URL-template syntax with `{name}` and `{style}` placeholders, env-var expansion in headers and params, the advanced registry config object, the server-side `registry.json` schema (items[] with name/type/title/description/files/ dependencies/registryDependencies/cssVars/tailwind), the nine registry:* item types, and content-negotiation headers used by the CLI. The CLI command surface itself lives in shadcn-core-cli. Keywords: shadcn registry, custom registry, private registry, components.json, registries field, namespace, namespaces, registry namespace, @namespace, @myorg, @v0, @shadcn, URL template, {name} placeholder, {style} placeholder, env var expansion, REGISTRY_TOKEN, bearer token, API key, registry headers, registry params, advanced registry config, registry.json, registry item schema, registry:ui, registry:component, registry:block, registry:hook, registry:lib, registry:page, registry:file, registry:style, registry:theme, cssVars, registryDependencies, target placeholder, shadcn build, public/r, host my own registry, internal design system, paid component library, immutable fields, baseColor cannot change, cssVariables immutable, style immutable, aliases mismatch, monorepo registry, content negotiation, Accept header, vnd.shadcn.v1+json, Authorization Bearer, X-API-Key, how do I publish components, how do I sell components, fallback to default registry, registry resolution order, what is components.json registries.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : Registry + components.json (Deep)

The shadcn registry is a code-distribution protocol, not a package index. A registry serves JSON descriptions of items (components, blocks, hooks, themes) ; the CLI fetches those descriptions and writes the embedded files into the consumer project. Every project carries a components.json that describes WHERE to write those files and WHICH registries to read from.

This skill covers the SCHEMA and the HOSTING model. The CLI command surface (init, add, view, search, build, migrate) lives in shadcn-core-cli. Do not duplicate command syntax here ; link out.

Quick Reference : Which Registry For Which Need

Q1. Are you installing PUBLIC shadcn components only?
    yes  → default `@shadcn` registry, no `registries` field needed
    no   → Q2

Q2. Do you need PRIVATE components (internal design system)?
    yes  → custom registry with `${ENV_VAR}`-expanded auth headers (Pattern 3)
    no   → Q3

Q3. Are you BUYING third-party components (paid registry)?
    yes  → vendor-supplied namespace + token, env-var-expanded (Pattern 3)
    no   → Q4

Q4. Are you publishing a registry for OTHER teams to consume?
    yes  → author `registry.json` + run `shadcn build`, serve `./public/r/*`
           (Pattern 5). The CONSUMER then adds your URL via `registries`.
    no   → you do NOT need to touch `registries` ; the default `@shadcn` works

ALWAYS pick the smallest configuration that meets the need. NEVER declare the @shadcn namespace in registries unless you are intentionally overriding the default URL or attaching headers to it.

Quick Reference : The Four Immutable Decisions

Three fields in components.json are IMMUTABLE after init (verified at https://ui.shadcn.com/docs/components-json) :

Field	Why immutable	What happens if you change it
style	The CLI fetches per-style JSON from the registry ({style} placeholder is a real construct). Already-installed files were templated against the original style.	Future add calls fetch new-style files ; existing files are unchanged. Visual drift across components.