What a component registry is

A component registry is an endpoint that exposes source files, dependencies and metadata in a format a CLI can install. It is not an npm package and it is not a catalogue page.

What a record contains

A registry.json file declares a name, a list of items and, for each item, a type (registry:ui, registry:block, registry:component), the files, the npm dependencies and the registryDependencies. shadcn/ui documents the schema under the MIT licence at ui.shadcn.com/docs/registry.

A minimal record, line by line

{
  "name": "hero",
  "type": "registry:block",
  "files": [{ "path": "hero.tsx", "type": "registry:component" }],
  "dependencies": ["lucide-react"],
  "registryDependencies": ["button", "card"]
}

The record declares no version and holds no component code: it says where to fetch it. files lists the paths the CLI writes into the project, dependencies are npm packages, registryDependencies are other records in the same registry, resolved before yours. With no version field there is no upgrade path: the installed copy is your copy.

How to install from one

npx shadcn@latest add button

The command writes files into your repository and updates components.json. With an explicit URL you install a remote record, for example npx shadcn@latest add https://example.com/r/hero.json; with a namespace, npx shadcn@latest add @eneui/hero. The code is yours: you can edit it after installation.

On 1 November 2026 the file data/shadcn_registries.json, a copy of the official directory, lists 525 registries, 517 of them with a health score of at least 50; data/custom_registries.json holds 415 already imported. The count reads both files, it does not estimate: it says how many endpoints exist, not how many are still maintained.

Public registry, private registry

A public registry answers without authentication. A private registry needs a token and usually a namespace declared in components.json; without a token the endpoint returns 401. The full path is in 401, 402 and 403 and in tokens and namespaces.

Why use one instead of a package

An npm package centralises updates and imposes an API. A registry distributes the code and leaves ownership with you: no lock-in, but no automatic updates either. The comparison of the two models is in copy-paste or headless.

The EneUI catalogue and its registry

EneUI indexes 111,985 components and 1,556 blocks. Every record shows the source library and the upstream licence, for example Magic UI rainbow button. The endpoint /api/registry/<library>/<name>.json returns 401 without a token: it is a private registry, not an anonymous public one. Checked on 1 November 2026.

The limitation

A registry moves files; it checks neither quality nor licence compatibility. Install ten records from ten different registries and you get ten styles and potentially conflicting versions of React. The registry will not stop you.

The decision rule

Pick a registry when the component will be edited and versioned together with the product. Pick an npm package when the same component serves three or more repositories and you want one bug fix. When in doubt open the record: more than five registryDependencies means you are installing a tree of files, not a component.

The mistake to avoid

Installing two records that bring the same primitive from different registries: two copies of dialog.tsx, two token sets, two Radix versions in the bundle. The CLI writes files, it does not deduplicate them. Before running the command, compare the registryDependencies in the record with what components/ui already holds.

Where to continue

The comparison of headless primitives is in Radix, Base UI and React Aria. To see what really lands in your repository read private registries; for the visual side start from the 1,556 blocks with previews.