feat(shadcn): add support for registries index (#8128)

* feat(shadcn): add support for registries index

* fix

* fix

* chore: changeset

* feat(shadcn): update handling of add commands

* feat: add support for known registries

* docs: update index docs

Author: shadcn

.changeset/good-crews-smile.md

@@ -0,0 +1,5 @@
+---
+"shadcn": minor
+---
+
+add support for registries index

apps/v4/content/docs/registry/meta.json

@@ -7,6 +7,7 @@
     "authentication",
     "examples",
     "mcp",
+    "registry-index",
     "open-in-v0",
     "registry-json",
     "registry-item-json"

apps/v4/content/docs/registry/namespace.mdx

@@ -41,7 +41,7 @@ Registry namespaces are prefixed with `@` and provide a way to organize and refe
 
 ## Decentralized Namespace System
 
-We intentionally designed the namespace system to be decentralized. There is no central registrar for namespaces. You are free to create and use any namespace you want.
+We intentionally designed the namespace system to be decentralized. There is [central registrar](/docs/registry/registrar) for open source namespaces but you are free to create and use any namespace you want.
 
 This decentralized approach gives you complete flexibility to organize your resources however makes sense for your organization.
 
@@ -615,82 +615,6 @@ Resolution order:
 2. **Circular Dependency Prevention**: Automatically detects and prevents circular dependencies
 3. **Smart Installation Order**: Dependencies are installed first, then the resources that use them
 
-We intentionally designed the namespace system to be decentralized. There is no central registrar for namespaces. You are free to create and use any namespace you want.
-
-This decentralized approach gives you complete flexibility to organize your resources however makes sense for your organization.
-
-You can create multiple registries for different purposes:
-
-```json title="components.json" showLineNumbers
-{
-  "registries": {
-    "@acme-ui": "https://registry.acme.com/ui/{name}.json",
-    "@acme-docs": "https://registry.acme.com/docs/{name}.json",
-    "@acme-ai": "https://registry.acme.com/ai/{name}.json",
-    "@acme-themes": "https://registry.acme.com/themes/{name}.json",
-    "@acme-internal": {
-      "url": "https://internal.acme.com/registry/{name}.json",
-      "headers": {
-        "Authorization": "Bearer ${INTERNAL_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-This allows you to:
-
-- **Organize by type**: Separate UI components, documentation, AI resources, etc.
-- **Organize by team**: Different teams can maintain their own registries
-- **Organize by visibility**: Public vs. private resources
-- **Organize by version**: Stable vs. experimental registries
-- **No naming conflicts**: Since there's no central authority, you don't need to worry about namespace collisions
-
-### Examples of Multi-Registry Setups
-
-#### By Resource Type
-
-```json title="components.json" showLineNumbers
-{
-  "@components": "https://cdn.company.com/components/{name}.json",
-  "@hooks": "https://cdn.company.com/hooks/{name}.json",
-  "@utils": "https://cdn.company.com/utils/{name}.json",
-  "@prompts": "https://cdn.company.com/ai-prompts/{name}.json"
-}
-```
-
-#### By Team or Department
-
-```json
-{
-  "@design": "https://design.company.com/registry/{name}.json",
-  "@engineering": "https://eng.company.com/registry/{name}.json",
-  "@marketing": "https://marketing.company.com/registry/{name}.json"
-}
-```
-
-#### By Stability
-
-```json title="components.json" showLineNumbers
-{
-  "@stable": "https://registry.company.com/stable/{name}.json",
-  "@latest": "https://registry.company.com/beta/{name}.json",
-  "@experimental": "https://registry.company.com/experimental/{name}.json"
-}
-```
-
----
-
-## Built-in Registries
-
-The `@shadcn` namespace is built-in and always available:
-
-```bash
-npx shadcn@latest add @shadcn/button
-```
-
-This is equivalent to installing from the default shadcn/ui registry.
-
 ---
 
 ## Versioning

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

@@ -0,0 +1,79 @@
+---
+title: Index
+description: Open Source Registry Index
+---
+
+The open source registry index is a list of all the open source registries that are available to use out of the box.
+
+When you run `shadcn add` or `shadcn search`, the CLI will automatically check the registry index for the registry you are looking for and add it to your `components.json` file.
+
+You can see the full list at [https://ui.shadcn.com/r/registries.json](https://ui.shadcn.com/r/registries.json).
+
+## Adding a Registry
+
+You can submit a PR to add a registry to the index by adding it to the [registries.json](https://github.com/shadcn-ui/ui/blob/main/apps/v4/public/r/registries.json) file.
+
+Here's an example of how to add a registry to the index:
+
+```json title="registries.json" showLineNumbers
+{
+  "@acme": "https://registry.acme.com/r/{name}.json",
+  "@example": "https://example.com/r/{name}"
+}
+```
+
+### Requirements
+
+1. The registry must be open source and publicly accessible.
+2. The registry must be a valid JSON file that conforms to the [registry schema specification](/docs/registry/registry-json).
+3. The registry is expected to be a flat registry with no nested items i.e `/registry.json` and `/component-name.json` files are expected to be in the root of the registry.
+4. The `files` array, if present, must NOT include a `content` property.
+
+Here's an example of a valid registry:
+
+```json title="registry.json" showLineNumbers
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "acme",
+  "homepage": "https://acme.com",
+  "items": [
+    {
+      "name": "login-form",
+      "type": "registry:component",
+      "title": "Login Form",
+      "description": "A login form component.",
+      "files": [
+        {
+          "path": "registry/new-york/auth/login-form.tsx",
+          "type": "registry:component"
+        }
+      ]
+    },
+    {
+      "name": "example-login-form",
+      "type": "registry:component",
+      "title": "Example Login Form",
+      "description": "An example showing how to use the login form component.",
+      "files": [
+        {
+          "path": "registry/new-york/examples/example-login-form.tsx",
+          "type": "registry:component"
+        }
+      ]
+    }
+    }
+  ]
+}
+```
+
+### Validation
+
+At the root of the `shadcn/ui` project, you can run the following command to validate the `registries.json` file.
+
+```bash
+pnpm validate:registries
+```
+
+This will validate the registries.json file and output any errors.
+
+Once you have submitted your PR, it will be validated and reviewed by the team.

packages/shadcn/src/commands/add.ts

@@ -14,6 +14,7 @@ import { getProjectInfo } from "@/src/utils/get-project-info"
 import { handleError } from "@/src/utils/handle-error"
 import { highlighter } from "@/src/utils/highlighter"
 import { logger } from "@/src/utils/logger"
+import { ensureRegistriesInConfig } from "@/src/utils/registries"
 import { updateAppIndex } from "@/src/utils/update-app-index"
 import { Command } from "commander"
 import prompts from "prompts"
@@ -76,6 +77,17 @@ export const add = new Command()
         })
       }
 
+      let hasNewRegistries = false
+      if (components.length > 0) {
+        const { config: updatedConfig, newRegistries } =
+          await ensureRegistriesInConfig(components, initialConfig, {
+            silent: options.silent,
+            writeFile: false,
+          })
+        initialConfig = updatedConfig
+        hasNewRegistries = newRegistries.length > 0
+      }
+
       if (components.length > 0) {
         const [registryItem] = await getRegistryItems([components[0]], {
           config: initialConfig,
@@ -134,6 +146,7 @@ export const add = new Command()
       let { errors, config } = await preFlightAdd(options)
 
       // No components.json file. Prompt the user to run init.
+      let initHasRun = false
       if (errors[ERRORS.MISSING_CONFIG]) {
         const { proceed } = await prompts({
           type: "confirm",
@@ -155,15 +168,18 @@ export const add = new Command()
           force: true,
           defaults: false,
           skipPreflight: false,
-          silent: true,
+          silent: options.silent || !hasNewRegistries,
           isNewProject: false,
           srcDir: options.srcDir,
           cssVariables: options.cssVariables,
           baseStyle: true,
+          components: options.components,
         })
+        initHasRun = true
       }
 
       let shouldUpdateAppIndex = false
+
       if (errors[ERRORS.MISSING_DIR_OR_EMPTY_PROJECT]) {
         const { projectPath, template } = await createProject({
           cwd: options.cwd,
@@ -187,12 +203,14 @@ export const add = new Command()
             force: true,
             defaults: false,
             skipPreflight: true,
-            silent: true,
+            silent: !hasNewRegistries && options.silent,
             isNewProject: true,
             srcDir: options.srcDir,
             cssVariables: options.cssVariables,
             baseStyle: true,
+            components: options.components,
           })
+          initHasRun = true
 
           shouldUpdateAppIndex =
             options.components?.length === 1 &&
@@ -206,7 +224,18 @@ export const add = new Command()
         )
       }
 
-      await addComponents(options.components, config, options)
+      const { config: updatedConfig } = await ensureRegistriesInConfig(
+        options.components,
+        config,
+        {
+          silent: options.silent || hasNewRegistries,
+        }
+      )
+      config = updatedConfig
+
+      if (!initHasRun) {
+        await addComponents(options.components, config, options)
+      }
 
       // If we're adding a single component and it's from the v0 registry,
       // let's update the app/page.tsx file to import the component.

packages/shadcn/src/commands/init.ts

@@ -8,7 +8,7 @@ import {
 } from "@/src/registry/api"
 import { buildUrlAndHeadersForRegistryItem } from "@/src/registry/builder"
 import { configWithDefaults } from "@/src/registry/config"
-import { BASE_COLORS } from "@/src/registry/constants"
+import { BASE_COLORS, BUILTIN_REGISTRIES } from "@/src/registry/constants"
 import { clearRegistryContext } from "@/src/registry/context"
 import { rawConfigSchema } from "@/src/schema"
 import { addComponents } from "@/src/utils/add-components"
@@ -38,6 +38,7 @@ import {
 import { handleError } from "@/src/utils/handle-error"
 import { highlighter } from "@/src/utils/highlighter"
 import { logger } from "@/src/utils/logger"
+import { ensureRegistriesInConfig } from "@/src/utils/registries"
 import { spinner } from "@/src/utils/spinner"
 import { updateTailwindContent } from "@/src/utils/updaters/update-tailwind-content"
 import { Command } from "commander"
@@ -175,6 +176,16 @@ export const init = new Command()
           createFileBackup(componentsJsonPath)
         }
 
+        // Ensure all registries used in components are configured.
+        const { config: updatedConfig } = await ensureRegistriesInConfig(
+          components,
+          shadowConfig,
+          {
+            silent: true,
+          }
+        )
+        shadowConfig = updatedConfig
+
         // This forces a shadowConfig validation early in the process.
         buildUrlAndHeadersForRegistryItem(components[0], shadowConfig)
 
@@ -266,6 +277,31 @@ export async function runInit(
     }
   }
 
+  // Prepare the list of components to be added.
+  const components = [
+    // "index" is the default shadcn style.
+    // Why index? Because when style is true, we read style from components.json and fetch that.
+    // i.e new-york from components.json then fetch /styles/new-york/index.
+    // TODO: Fix this so that we can extend any style i.e --style=new-york.
+    ...(options.baseStyle ? ["index"] : []),
+    ...(options.components ?? []),
+  ]
+
+  // Ensure registries are configured for the components we're about to add.
+  const fullConfigForRegistry = await resolveConfigPaths(options.cwd, config)
+  const { config: configWithRegistries } = await ensureRegistriesInConfig(
+    components,
+    fullConfigForRegistry,
+    {
+      silent: true,
+    }
+  )
+
+  // Update config with any new registries found.
+  if (configWithRegistries.registries) {
+    config.registries = configWithRegistries.registries
+  }
+
   const componentSpinner = spinner(`Writing components.json.`).start()
   const targetPath = path.resolve(options.cwd, "components.json")
   const backupPath = `${targetPath}${FILE_BACKUP_SUFFIX}`
@@ -279,20 +315,20 @@ export async function runInit(
     config = { ...merged, registries }
   }
 
+  // Make sure to filter out built-in registries.
+  // TODO: fix this in ensureRegistriesInConfig.
+  config.registries = Object.fromEntries(
+    Object.entries(config.registries || {}).filter(
+      ([key]) => !Object.keys(BUILTIN_REGISTRIES).includes(key)
+    )
+  )
+
   // Write components.json.
   await fs.writeFile(targetPath, `${JSON.stringify(config, null, 2)}\n`, "utf8")
   componentSpinner.succeed()
 
   // Add components.
   const fullConfig = await resolveConfigPaths(options.cwd, config)
-  const components = [
-    // "index" is the default shadcn style.
-    // Why index? Because when style is true, we read style from components.json and fetch that.
-    // i.e new-york from components.json then fetch /styles/new-york/index.
-    // TODO: Fix this so that we can extend any style i.e --style=new-york.
-    ...(options.baseStyle ? ["index"] : []),
-    ...(options.components ?? []),
-  ]
   await addComponents(components, fullConfig, {
     // Init will always overwrite files.
     overwrite: true,

packages/shadcn/src/commands/search.ts

@@ -7,6 +7,7 @@ import { rawConfigSchema } from "@/src/schema"
 import { loadEnvFiles } from "@/src/utils/env-loader"
 import { createConfig, getConfig } from "@/src/utils/get-config"
 import { handleError } from "@/src/utils/handle-error"
+import { ensureRegistriesInConfig } from "@/src/utils/registries"
 import { Command } from "commander"
 import fsExtra from "fs-extra"
 import { z } from "zod"
@@ -84,6 +85,19 @@ export const search = new Command()
         // Use shadow config if getConfig fails (partial components.json).
       }
 
+      const { config: updatedConfig, newRegistries } =
+        await ensureRegistriesInConfig(
+          registries.map((registry) => `${registry}/registry`),
+          config,
+          {
+            silent: true,
+            writeFile: false,
+          }
+        )
+      if (newRegistries.length > 0) {
+        config.registries = updatedConfig.registries
+      }
+
       // Validate registries early for better error messages.
       validateRegistryConfigForItems(registries, config)