Build and serve a shadcn registry

Start with the two registry forms

A source registry is the structure you maintain in your repository. It can reference real source files and split definitions across multiple registry.json files with include.

A built registry is the distribution output. It contains a flattened catalog plus one self-contained JSON payload per item. A hosted registry serves those generated files; the installer consumes the item payload, not your source tree. This source-versus-built distinction is also the model used by the official getting-started guide.

Create a source layout

The tested fixture used this small project structure:

registry.json
components/
└── ui/
    ├── registry.json
    └── hello-card.tsx

The root file owns the registry name and homepage. Its include points to the exact nested registry file:

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme",
  "homepage": "https://example.com",
  "include": ["components/ui/registry.json"]
}

The nested file owns the item. Because it declares the item, its file path is relative to that nested registry.json:

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "items": [
    {
      "name": "hello-card",
      "type": "registry:ui",
      "title": "Hello Card",
      "description": "A small card used to verify the registry build.",
      "files": [
        {
          "path": "hello-card.tsx",
          "type": "registry:ui"
        }
      ]
    }
  ]
}

export function HelloCard() {
  return <div>Hello from the registry.</div>
}

Included files may omit the root metadata. Item names must remain unique across the resolved registry. See the official include rules for the schema constraints.

Build the distribution files

Run the command from the directory containing the root registry:

npx shadcn@latest build

# Equivalent explicit paths:
npx shadcn@latest build registry.json --output public/r

The tested build produced:

public/r/
├── registry.json
└── hello-card.json

The generated catalog contained the resolved item and no include. The item payload contained the file path and the actual source text. That flattening is why generated output should be treated as a build artifact rather than another source registry.

Serve the catalog and item endpoints

Deploy the generated directory as static files. With the default output, a framework that serves public at the site root exposes:

https://example.com/r/registry.json
https://example.com/r/hello-card.json

Both URLs should return the JSON directly with a successful status. Do not point an item URL at an HTML documentation page or a client-side route that only later fetches the JSON.

curl --fail https://example.com/r/registry.json
curl --fail https://example.com/r/hello-card.json
npx shadcn@latest view https://example.com/r/hello-card.json

Give consumers a stable install address

A direct URL is the simplest final check. For a named registry, consumers can map a namespace to your item URL template in components.json:

{
  "registries": {
    "@acme": "https://example.com/r/{name}.json"
  }
}

npx shadcn@latest add @acme/hello-card

If you instead publish a public GitHub source registry, the CLI can read the root source registry directly. That is a separate distribution model; do not mix its source address with a hosted item URL in documentation.

Common build and hosting mistakes

• Including a directory. The CLI rejected "components/ui" and required an explicit path such as "components/ui/registry.json".
• Resolving files from the wrong place. Keep file paths relative to the registry file that declares the item, and run the build from the intended project directory or pass --cwd.
• Publishing only the catalog. Discovery may work while installation fails if sibling item JSON files are missing.
• Serving stale output. Rebuild before deployment and verify the deployed payload, not only the local source file.
• Duplicating item names. Names must be unique after all includes are resolved.

Next step

Building is only the first gate. Continue with the handbook’s validation and listing checklist, or use the existing registry inspector to inspect a public catalog or item payload.