shadcn build - shadcn/ui

The build command builds components for a shadcn/ui registry. Use it to create a custom registry by bundling your component files into registry JSON files.

Usage

shadcn build [registry]

Arguments

string

default:"./registry.json"

Path to the registry.json file. Defaults to ./registry.json in the current directory.

Options

string

default:"./public/r"

Destination directory for JSON files. Defaults to ./public/r.

string

The working directory. Defaults to the current directory.

Examples

Build with default paths

shadcn build

Builds from ./registry.json to ./public/r.

Build from custom registry file

shadcn build ./src/registry.json

Build to custom output directory

shadcn build --output ./dist/registry

Build with custom paths

shadcn build ./custom-registry.json --output ./build/r

Build in specific directory

shadcn build --cwd ./packages/ui

What it does

Reads the registry.json file
Validates the registry schema
For each registry item:
- Reads the source files from disk
- Embeds file content into the registry item
- Adds the JSON schema URL
- Validates the complete registry item
- Writes a JSON file to the output directory
Copies registry.json to the output directory

Registry structure

Your registry.json should follow this structure:

{
  "name": "my-registry",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "files": [
        {
          "path": "components/ui/button.tsx",
          "type": "registry:ui"
        }
      ],
      "dependencies": [
        "@radix-ui/react-slot"
      ]
    }
  ]
}

Output structure

After building, your output directory will contain:

public/r/
├── registry.json
├── button.json
├── card.json
└── dialog.json

Each component JSON file includes the source code:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "button",
  "type": "registry:ui",
  "files": [
    {
      "path": "components/ui/button.tsx",
      "type": "registry:ui",
      "content": "import * as React from \"react\"\n...full source code..."
    }
  ],
  "dependencies": [
    "@radix-ui/react-slot"
  ]
}

Registry item fields

Each item in registry.json can include:

string

required

Unique identifier for the component.

string

required

Registry type: registry:ui, registry:block, registry:hook, registry:lib, etc.

array

required

Array of file objects with path and optional type.

array

npm packages required by the component.

array

npm dev packages required by the component.

array

Other registry components required by this component.

object

Additional metadata (description, tags, etc.).

Creating a custom registry

1. Create registry.json

{
  "name": "my-ui",
  "items": [
    {
      "name": "custom-button",
      "type": "registry:ui",
      "files": [
        {
          "path": "src/components/custom-button.tsx"
        }
      ],
      "dependencies": ["clsx"]
    }
  ]
}

2. Build the registry

shadcn build

3. Serve the registry

Deploy the public/r directory to a web server or CDN.

4. Use the registry

Add to components.json:

{
  "registries": {
    "@my-ui": {
      "url": "https://my-registry.com/r"
    }
  }
}

Install components:

shadcn add @my-ui/custom-button

Validation

The build command validates:

Registry schema - Ensures registry.json is valid
Registry item schema - Validates each component’s metadata
File existence - Checks that all referenced files exist

If validation fails, the build will:

Log an error message
Skip the invalid item
Continue building other items

Use cases

Internal component library

Build a private registry for your organization:

shadcn build ./company-registry.json --output ./dist/registry

Open source components

Share your components publicly:

shadcn build
# Deploy public/r to GitHub Pages or Vercel

Monorepo packages

Build registries for multiple packages:

shadcn build --cwd ./packages/ui --output ./packages/ui/dist/r
shadcn build --cwd ./packages/blocks --output ./packages/blocks/dist/r

Output

✔ Building registry...
✔ Building button...
✔ Building card...
✔ Building dialog...
✔ Building registry.

Error handling

Invalid registry file

Invalid registry file found at ./registry.json.

Solution: Validate your JSON syntax and schema.

Invalid registry item

Invalid registry item found for button.

Solution: Check that all required fields are present and valid.

File not found

If a referenced file doesn’t exist, the build will fail. Ensure all paths in files arrays are correct and relative to the cwd.

Notes

File paths in registry.json should be relative to the working directory
The build embeds full file content, so output files can be large
Output is production-ready JSON for hosting
Schema URLs are automatically added to built files
Original registry.json is copied to output directory
Safe to run multiple times (overwrites previous build)

⌘I

​Usage

​Arguments

​Options

​Examples

​Build with default paths

​Build from custom registry file

​Build to custom output directory

​Build with custom paths

​Build in specific directory

​What it does

​Registry structure

​Output structure

​Registry item fields

​Creating a custom registry

​1. Create registry.json

​2. Build the registry

​3. Serve the registry

​4. Use the registry

​Validation

​Use cases

​Internal component library

​Open source components

​Monorepo packages

​Output

​Error handling

​Invalid registry file

​Invalid registry item

​File not found

​Notes

Usage

Arguments

Options

Examples

Build with default paths

Build from custom registry file

Build to custom output directory

Build with custom paths

Build in specific directory

What it does

Registry structure

Output structure

Registry item fields

Creating a custom registry

1. Create registry.json

2. Build the registry

3. Serve the registry

4. Use the registry

Validation

Use cases

Internal component library

Open source components

Monorepo packages

Output

Error handling

Invalid registry file

Invalid registry item

File not found

Notes