Registry Directory

Purpose and Scope

The Registry Directory is the discovery page for community registries that can be used with shadcn/ui. A registry is a JSON-served catalog of installable code such as components, blocks, hooks, pages, config, rules, and related files. The directory page is specifically about community registries that are already known to the shadcn tooling, so a user can install from a namespace without first hand-editing configuration. The page’s primary task is to help readers move from “I want a component or block from the ecosystem” to the concrete command form npx shadcn add @<registry>/<component>.

Sources: apps/v4/content/docs/(root)/directory.mdx, packages/shadcn/src/registry/search.ts

This directory sits beside, but is not the same thing as, the registry authoring documentation. The directory page presents discovered registries and links onward to the guides for creating, securing, namespacing, and validating registries. The surrounding registry docs navigation confirms that registry topics are a formal docs family rather than a single page: introduction, getting started, GitHub registries, registry index, examples, namespace, authentication, MCP, API reference, and schema references all live under the Registry section. That structure matters because directory users often become registry authors after they validate a namespace or publish reusable blocks.

Sources: apps/v4/content/docs/(root)/directory.mdx, apps/v4/content/docs/registry/meta.json

Relevant Source Files

apps/v4/content/docs/(root)/directory.mdx — Defines the public Registry Directory page, its reader-facing description, the DirectoryList insertion point, the install command pattern, the security callout, and links into registry documentation.
apps/v4/content/docs/registry/meta.json — Defines the Registry documentation section ordering, including registry-index, namespace, authentication, registry schema pages, and related reference pages that directory readers are expected to use next.
packages/shadcn/src/registry/search.ts — Implements registry search behavior used by the CLI and MCP server, including how configured registries are selected, how searches are run concurrently, how failures can be collected, and how deterministic ordering is preserved.

How Users Discover and Install Registry Items

The simplest directory workflow is browse, choose a registry namespace, then install a named item. The directory page states that listed community registries are built into the CLI with no additional configuration required, and it gives the exact command shape: npx shadcn add @<registry>/<component>. The @<registry> part is the namespace, and <component> is the registry item name. This keeps installation ergonomic for consumers because the namespace identifies the registry source while the item name identifies the code artifact to fetch and add to the project.

Sources: apps/v4/content/docs/(root)/directory.mdx

npx shadcn add @<registry>/<component>

Directory discovery is also intentionally connected to search. The official registry-index behavior explains that shadcn add and shadcn search can check the open source registry index and add a discovered registry to components.json when needed. In code, search begins by resolving which registries to target. If the caller passes explicit registries, those are used. If no registries are passed, resolveSearchRegistries reads the project configuration and returns configured registries while excluding builtin registries such as @shadcn. This makes “search all” mean “search the user’s configured ecosystem,” not “search every internal source.”

Sources: packages/shadcn/src/registry/search.ts

resolveSearchRegistries(registries, config)
searchRegistries(registries, { query, types, limit, offset, config, useCache, continueOnError })

System-to-Code Mapping

The rendered docs page is centered on DirectoryList, which is the directory’s catalog placeholder. The surrounding MDX provides the context users need before interacting with that catalog: the page title and description define the feature as discovery for community registries, the first paragraph promises no extra configuration for listed registries, and the callout warns that community registries are maintained by third-party developers. That warning is part of the product contract. shadcn/ui makes third-party code easy to install, but the docs tell users to review code during installation for security and quality before relying on it in an application.

Sources: apps/v4/content/docs/(root)/directory.mdx

The navigation metadata complements that page by showing where directory tasks branch. A reader who only wants to consume a component can stay on the directory page. A reader who wants to publish a registry can follow “Add a Registry” into the registry index guide. A reader who needs a private or protected source can follow Authentication. A reader who wants stable short names can follow Namespaces. A reader validating JSON structure can follow Schema. This is a deliberate documentation topology: discovery remains lightweight, while operational responsibilities are delegated to specialized registry pages.

Sources: apps/v4/content/docs/(root)/directory.mdx, apps/v4/content/docs/registry/meta.json

At runtime, the CLI-side search implementation gives the directory ecosystem a predictable operational shape. searchRegistries clears registry context before each search so a previous registry operation does not leak header context into the next one. It fetches registry catalogs with getRegistry, caps concurrent registry fetches with SEARCH_CONCURRENCY, and processes settled results in the original input order. That ordering guarantee is important for a directory experience because search output should not reshuffle merely because one registry responded faster than another.

Sources: packages/shadcn/src/registry/search.ts

Search Behavior and Failure Handling

Registry discovery can involve many third-party endpoints, so the search code avoids unbounded network fan-out. The exported SEARCH_CONCURRENCY constant is set to 8, and the helper mapSettledWithConcurrency runs at most that many asynchronous fetches at a time. It stores each result at the original input index and returns settled results, similar to Promise.allSettled. This means a large configured registry set can be searched without opening an uncontrolled number of connections, while still allowing the CLI or MCP server to present results deterministically.

Sources: packages/shadcn/src/registry/search.ts

The error model is also tuned for discovery. searchRegistries accepts continueOnError. When it is false, a registry fetch failure throws and aborts the search. When it is true, a failing registry is skipped and an error record containing the registry name and message is added to the returned errors collection. That option is especially useful for “search across many configured registries,” where one unavailable community endpoint should not necessarily prevent useful results from other registries. For directory users, this explains why search tools may show partial results alongside registry-specific errors.

Sources: packages/shadcn/src/registry/search.ts

Search options also expose the axes a consumer would expect from a registry directory: query for text matching, types for narrowing by registry item type, limit and offset for paging, config for project-specific registry configuration, and useCache for cache-aware retrieval. The file imports fuzzysort and registry result schemas, which shows that search is not only a network fetch but also a structured operation over validated registry items. The public directory page stays simple, but the CLI implementation has the pieces needed for filtered, paginated, and type-aware discovery.

Sources: packages/shadcn/src/registry/search.ts

Adding and Evaluating Community Registries

If a registry is not listed, the directory page points readers to the registry index guide rather than embedding the full contribution process. The official registry index guidance frames the open source registry index as the list of registries available out of the box and distinguishes it from direct public GitHub registry addresses. In practical terms, a public GitHub registry can still be used by address, while the directory is most valuable for namespaces such as @acme. The directory page therefore serves consumers first, and it routes maintainers to the registry index workflow when they want namespace-level discoverability.

Sources: apps/v4/content/docs/(root)/directory.mdx, apps/v4/content/docs/registry/meta.json

Before installing from a community registry, treat the installed files like any other third-party source code. shadcn/ui’s registry model distributes code into your project, so the right review questions are concrete: what files will be written, which packages are introduced, whether the component follows your design and accessibility standards, and whether hooks or configuration changes match your application conventions. The directory callout explicitly says community registries are third-party maintained and instructs users to review code on installation. That warning should be part of every production workflow, not a one-time onboarding note.

Sources: apps/v4/content/docs/(root)/directory.mdx

Next Steps

To consume a directory item, start with the namespace command and review the diff before committing the generated files. To search across registries, use the CLI or MCP flows that rely on the shared search behavior in packages/shadcn/src/registry/search.ts. To publish your own namespace, continue to the registry index and namespace documentation. To operate a protected registry, read the authentication guide. To validate a registry catalog or item payload, use the registry schema pages. The directory is intentionally the front door; the linked registry docs are the place to handle authoring, validation, and long-term maintenance.

Sources: apps/v4/content/docs/(root)/directory.mdx, apps/v4/content/docs/registry/meta.json, packages/shadcn/src/registry/search.ts

Ask a question...