Registry Namespaces

Purpose and Scope

Registry namespaces let one project install resources from more than one registry without treating every registry as a special case. A namespace is the @-prefixed part of an address, such as @acme in @acme/auth-utils. The item name follows the slash. The docs describe resources broadly: components, libraries, utilities, hooks, AI prompts, configuration files, themes, docs, workflow files, and other project assets can all be distributed through the registry system. This matters because the shadcn/ui registry model is no longer only a component catalog; it is a way to move reusable code and conventions between projects.

Sources: apps/v4/content/docs/registry/namespace.mdx, apps/v4/content/docs/changelog/2025-02-registry-schema.mdx, apps/v4/content/docs/changelog/2025-07-universal-registry.mdx

Namespaces solve two related problems. First, they give users a readable install address, such as @ai-elements/input or @themes/dark-mode, instead of requiring a long URL every time. Second, they let teams decide how to organize registries: by resource type, team, visibility, or stability. The namespace page emphasizes that the system is intentionally decentralized. There is a central open source registry index for discoverable public namespaces, but a project can still define any namespace in components.json and point it at an internal or third-party registry endpoint.

Relevant Source Files

apps/v4/content/docs/registry/namespace.mdx - primary reader-facing guide for namespaced registries, including address examples, decentralized naming, components.json configuration, authentication, dependency resolution, CLI usage, and troubleshooting topics.
apps/v4/content/docs/registry/github.mdx - explains the parallel GitHub address form, when owner/repo/item is appropriate, and why private or authenticated registries should use namespaces instead.
apps/v4/content/docs/changelog/2025-02-registry-schema.mdx - records the registry schema expansion that supports custom styles, third-party registries, themes, hooks, animations, Tailwind layers, and utilities.
apps/v4/content/docs/changelog/2025-07-universal-registry.mdx - establishes universal registry items that can distribute code, config, rules, docs, or other files without requiring React, Tailwind, a framework, or components.json.
apps/v4/content/docs/changelog/2025-09-registry-index.mdx - introduces the open source registry index and the ability to add indexed namespaces without manually configuring components.json first.
apps/v4/content/docs/changelog/2025-10-registry-directory.mdx - introduces the Registry Directory as a browsable list of code registries that the CLI can use without upfront configuration.

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

Address Forms and Resolution Model

A namespaced registry address has two required pieces: the namespace and the resource name. In the address @shadcn/button, @shadcn identifies the registry source and button identifies the item requested from that source. In @v0/dashboard, the same parsing rule points at a different registry. The docs use examples such as @ai-elements/input, @acme/auth-utils, @ai/chatbot-rules, and @themes/dark-mode to show that the item name does not imply a specific file type. The registry item itself decides what files, dependencies, CSS variables, or other resources are installed.

The namespace is resolved through project configuration or through registry discovery. In components.json, the registries object maps a namespace to either a URL template string or an object with a URL and request metadata. The URL template contains {name}, which is replaced by the item portion of the address. For example, @acme-ui can map to https://registry.acme.com/ui/{name}.json, while @acme-internal can map to an object that includes headers. This keeps the install command stable even if the backing host, path structure, or authentication strategy changes.

{
  "registries": {
    "@acme-ui": "https://registry.acme.com/ui/{name}.json",
    "@acme-internal": {
      "url": "https://internal.acme.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}

Registry addresses also appear inside registry item metadata. The registry item schema supports registryDependencies, and the official example includes plain names, namespaced names such as @acme/input-form, and full URLs. That means dependency resolution is not limited to the registry currently being installed from. A registry item can depend on a core item, another namespace, or an explicit remote item. When authoring registries, use namespaced dependencies when the dependency belongs to a specific external source and use plain names only when the current registry or built-in behavior makes the source unambiguous.

Configuration Patterns

The most direct pattern is to configure multiple namespaces in components.json for the same project. The namespace guide shows examples organized by resource type, such as @components, @hooks, @utils, and @prompts; by team, such as @design, @engineering, and @marketing; and by stability, such as stable and latest registries. These examples are not just naming preferences. They affect how readers reason about ownership, review requirements, security boundaries, and update cadence. A design-system registry may be treated as trusted UI infrastructure, while an experimental AI prompt registry may be reviewed differently.

For private or protected sources, configure the namespace as an object instead of a bare URL. The docs show an authenticated registry using headers and an environment variable placeholder. This keeps secrets out of the committed address while letting the CLI build authenticated requests at install time. The GitHub registry guide draws a clear boundary here: owner/repo/item works for public GitHub repositories with a root registry.json, but private repositories and GitHub Enterprise hosts are not supported by GitHub addresses. For private access, custom request headers, or protected endpoints, use a namespace with authentication configuration.

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

Discovery, Index, and Directory

Namespaces can be configured locally, but shadcn/ui also supports discovery for public open source registries. The September 2025 registry index changelog says users can search, view, and add items from the registry index without manually editing components.json; the registry is automatically added when needed. The example command is npx shadcn add @ai-elements/prompt-input, which demonstrates the user experience the index enables: the install address remains namespaced, but the user does not have to know the registry endpoint before trying the item.

The October 2025 Registry Directory builds on that direction by making registries browsable and available through the CLI with no config required. The distinction is useful for documentation and support. A local namespace mapping is the most explicit and controllable option. The open source registry index helps resolve known public namespaces. The directory helps users browse and discover registries before deciding what to install. In all three cases, the user-facing address keeps the same shape: a namespace plus an item name.

GitHub registries are a neighboring address system, not a replacement for namespaces. A public GitHub repository can become a registry by adding registry.json at the repository root, and users install with npx shadcn@latest add <username>/<repo>/<item>. This is convenient when reusable files already live in a public repository and no registry server is needed. Namespaces remain the better fit when the source needs authentication, when the organization wants a stable symbolic prefix, or when the same project uses many registries with different ownership models.

npx shadcn add @ai-elements/prompt-input
npx shadcn@latest add <username>/<repo>/<item>

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

Compact Reference

Concept	Concrete form	Use it for
Namespaced item	`@namespace/name`	Installing an item from a configured or indexed registry.
Local namespace mapping	`components.json` `registries`	Binding `@acme` or another prefix to a registry URL template.
URL template placeholder	`{name}`	Substituting the item name into the registry item JSON URL.
Authenticated registry	`registries["@scope"].headers`	Sending tokens or other headers to private registry endpoints.
Registry dependency	`registryDependencies`	Declaring dependencies on plain items, namespaced items, or URLs.
Public GitHub address	`<username>/<repo>/<item>`	Installing from a public repository that has root `registry.json`.
Indexed public namespace	`@ai-elements/prompt-input`	Installing from a known open source namespace without prior local config.

A practical namespace setup starts with the source of truth. If your registry is a normal HTTP endpoint, add a registries entry in components.json and use a URL template ending in the item JSON path. If the registry is private, use an object with headers and environment variable placeholders. If the registry is public and intended for broad discovery, consider the registry index and directory workflow so users can install by namespace without copying configuration. If the source is simply a public GitHub repository, use the GitHub address form instead of inventing a namespace unless you need a stable branded prefix.

Implementation Notes for Registry Authors

The changelog history explains why namespaces are more powerful than a package-style component alias. The February 2025 registry schema update broadened registry content to include custom styles, third-party registry composition, themes, hooks, animations, and Tailwind layers. The July 2025 universal registry update removed assumptions about framework, React, Tailwind, and even components.json for universal items. Namespaces sit on top of that broader content model: they point to registry items, and registry items can carry many kinds of files and installation metadata.

For authors, the important design constraint is predictability. Choose namespace names that communicate ownership and expected stability. Keep item names unique within a registry. Use registryDependencies to make cross-registry requirements explicit rather than relying on readers to install prerequisites manually. Prefer a public GitHub registry for simple public distribution from an existing repository, but prefer a namespace when you need authentication, multiple registries in one project, or a prefix that can outlive a particular host. After that, test the consumer experience by running the same shadcn add command your users will run.

Sources: apps/v4/content/docs/changelog/2025-02-registry-schema.mdx, apps/v4/content/docs/changelog/2025-07-universal-registry.mdx, apps/v4/content/docs/registry/namespace.mdx

Next Steps

Read the Registry Index page when you want public namespace discovery and automatic components.json updates. Read Registry Authentication when the namespace points at a private endpoint or requires headers. Read Registry Schema and Registry Item JSON when authoring the payloads that a namespace resolves to. If your reusable files already live in a public GitHub repository, compare the GitHub Registries guide before adding a custom namespace; the simpler owner/repo/item address may be enough for public, unauthenticated distribution.

Ask a question...