Registry Index

Purpose and Scope

The registry index is the discovery layer for open source registries that the shadcn CLI can use without a reader manually preconfiguring every source. In the public docs it is described as a list of registries available out of the box, and the changelog frames the feature as a way to search, view, and add indexed items without first editing project configuration. This matters for teams that publish reusable UI kits, workflow files, templates, or conventions: the consumer can type a namespaced item address, let the CLI find the matching registry, and continue with the normal installation flow instead of copying registry URLs by hand.

Sources: apps/v4/content/docs/changelog/2025-09-registry-index.mdx, apps/v4/content/docs/registry/registry-index.mdx

The index sits inside the broader registry system, which the docs define as a distribution system for code rather than only a React component marketplace. A registry can distribute custom components, hooks, pages, configuration, rules, and other files to any project type. That framing is important when reading index behavior: the index is not the registry itself, and it is not a package manager. It is a public directory that helps the CLI locate a registry source when a user asks for an item by namespace or searches for available items.

Sources: apps/v4/content/docs/registry/index.mdx, apps/v4/content/docs/registry/registry-index.mdx

Relevant Source Files

• apps/v4/content/docs/changelog/2025-09-registry-index.mdx — Announces the registry index update and documents the user-facing behavior: indexed registries can be searched, viewed, and added without manual project configuration.
• apps/v4/content/docs/registry/github.mdx — Explains how any public GitHub repository can act as a registry, including address form, requirements, and the range of files a registry item can distribute.
• apps/v4/content/docs/registry/index.mdx — Defines registries as a general code distribution system and links the registry guide family that surrounds index usage.
• apps/v4/content/docs/registry/registry-index.mdx — Provides the main registry index documentation, including automatic CLI lookup, directory submission steps, and requirements for indexed registries.
• apps/v4/registry/bases/aria/blocks/preview-02/index.tsx — Shows a concrete registry block preview composed from many local UI card modules, illustrating that registry content can be substantial application UI assembled from source files.
• apps/v4/registry/bases/aria/blocks/preview-03/index.tsx — Shows the minimal shape of another block preview export, useful as a contrast with the larger preview example.

How Item Discovery Works

When a user runs the CLI with an indexed address, the documented flow is intentionally low-friction. The changelog shows an example add command for an indexed namespace and says the registry will be added to the project configuration automatically. The registry index page makes the same point for both add and search operations: the CLI checks the index for the registry being requested and updates the project configuration when it finds a match. In practical terms, the first successful use of an indexed namespace teaches the project where that registry lives, so future operations can proceed through normal registry resolution.

Sources: apps/v4/content/docs/changelog/2025-09-registry-index.mdx, apps/v4/content/docs/registry/registry-index.mdx

The index is especially useful for namespace-style addresses such as an organization or publisher prefix. The docs explicitly distinguish this from direct GitHub addresses: a public GitHub registry does not need to be submitted to the directory for users to install with an owner, repository, and item address. That distinction prevents two discovery paths from being confused. Use the registry index when you want a stable namespace like a branded registry name. Use a direct GitHub address when the repository identity itself is the locator and public GitHub is the desired distribution channel.

Sources: apps/v4/content/docs/registry/github.mdx, apps/v4/content/docs/registry/registry-index.mdx

Registry Sources and File-Based Content

A registry item is not limited to a prebuilt package or a single component file. The GitHub registry guide says a public repository can become the source registry by placing a registry manifest at the repository root, and it lists examples that include components, helpers, design tokens, feature kits, agent workflows, project conventions, codemods, tests, workflows, issue templates, and MCP configuration. The requirement is that source files referenced by the registry definitions exist in the repository and that the registry and item documents conform to the schemas. This is the source-backed meaning of file-based support in the supplied evidence.

Sources: apps/v4/content/docs/registry/github.mdx

The block preview files demonstrate why that file model matters. One ARIA preview imports many card modules and renders a wide captured layout, while another preview exports a minimal placeholder component. Both are valid source files inside the registry tree, but they represent very different levels of content complexity. A registry item can therefore point at a composed application surface, a small component, a hook, configuration, or supporting files as long as the registry metadata describes them correctly. The index helps users find the registry, but the registry item definition still governs what gets installed.

Sources: apps/v4/registry/bases/aria/blocks/preview-02/index.tsx, apps/v4/registry/bases/aria/blocks/preview-03/index.tsx

Adding a Registry to the Index

To add a registry to the public index, the docs describe a repository contribution workflow. The registry owner adds their registry entry to the directory data, runs the validation command, and opens a pull request to the main project. After submission, the team validates and reviews the request. This process keeps the public index curated while still making discovery broadly available for open source registries. It also separates registry publication from application installation: a publisher prepares a valid public registry, then asks for namespace discovery to be added through review.

Sources: apps/v4/content/docs/registry/registry-index.mdx

The requirements are intentionally conservative. The registry must be open source, publicly accessible, and valid against the registry schema. The docs also require a flat registry shape, where the registry manifest and item JSON files are expected at the root level rather than nested under arbitrary folders. If file entries are present, they must not include embedded content in the public directory submission. Those constraints make indexed registries easier for the CLI and validators to fetch, inspect, and reason about consistently across many publishers.

Sources: apps/v4/content/docs/registry/registry-index.mdx

Compact Reference

Example indexed installation flow:

npx shadcn add @ai-elements/prompt-input

Example direct GitHub registry flow:

npx shadcn@latest add <username>/<repo>/<item>

Example validation step for a registry index contribution:

pnpm validate:registries

The reference table should be read as user-facing behavior, not as a replacement for the schema pages. The index tells the CLI where a registry is, while registry and item schemas describe what that registry contains. If an installation fails after discovery, the likely next checks are schema validity, item naming, file paths, public accessibility, or authentication strategy rather than the index alone. If a publisher is using a public GitHub address directly, the next check is whether the repository has a root registry manifest and whether the referenced source files actually exist.

Sources: apps/v4/content/docs/registry/github.mdx, apps/v4/content/docs/registry/registry-index.mdx

Edge Cases and Design Guidance

The most common design decision is whether to pursue index inclusion at all. If a team only wants to share from a public repository and is comfortable with addresses tied to the repository name, direct GitHub registry usage is enough. If the team wants a shorter namespace, a stable brand, or CLI discovery through search and add without manual configuration, the registry index is the better fit. The docs make clear that public GitHub submission is not a prerequisite for owner and repository addresses, so index review should be reserved for namespace discovery rather than treated as a publication gate.

Sources: apps/v4/content/docs/registry/github.mdx, apps/v4/content/docs/registry/registry-index.mdx

Another important edge case is assuming that registry items are React-only because shadcn/ui is known for components. The registry introduction explicitly says the registry works with any project type and framework, and the GitHub guide expands the range of supported content to documentation, rules, workflows, templates, automation, and MCP configuration. The preview block files show React examples because this repository contains UI blocks, but the registry model itself is broader. When designing an indexed registry, describe each item accurately and avoid hiding unrelated project conventions inside a component-shaped entry.

Sources: apps/v4/content/docs/registry/index.mdx, apps/v4/content/docs/registry/github.mdx, apps/v4/registry/bases/aria/blocks/preview-02/index.tsx

Next Steps

Readers who are consuming indexed items should start with add or search, then inspect the generated project configuration after the first namespaced install. Publishers should validate that their registry is public, flat, schema-compliant, and free of embedded file content in indexed file arrays before opening a contribution. For deeper implementation tasks, read the registry overview to understand the distribution model, the GitHub registry guide to choose between repository addresses and namespaces, the registry schema page to validate manifests, and the namespace and authentication pages when discovery needs to point at protected or branded registry sources.