# How the Component Registry Item Schema Defines Dependencies in shadcn/ui

> Learn how the shadcn/ui component registry item schema defines dependencies using dependencies devDependencies and registryDependencies arrays. Understand component requirements.

- Repository: [shadcn-ui/ui](https://github.com/shadcn-ui/ui)
- Tags: internals
- Published: 2026-02-26

---

**The component registry item schema defines three distinct dependency arrays—`dependencies`, `devDependencies`, and `registryDependencies`—that specify runtime packages, development tools, and inter-component relationships required for each shadcn/ui component.**

The shadcn/ui component registry relies on a strict JSON schema to standardize how components declare their requirements. The **component registry item schema**, located at [`apps/v4/public/schema/registry-item.json`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/public/schema/registry-item.json), enforces a structured format for metadata including the critical dependency fields that determine what gets installed alongside a component.

## The Three Dependency Types in the Component Registry Item Schema

The schema recognizes three distinct categories of dependencies, each serving a different purpose in the component lifecycle.

### Runtime Dependencies

The **`dependencies`** array (lines 39-45 of the schema) lists NPM packages required for the component to execute in production. These packages are installed into the consuming project's `dependencies` section.

### Development Dependencies

The **`devDependencies`** array (lines 46-52) specifies packages needed only during development, testing, or building. These might include TypeScript definitions, testing libraries, or build tools that don't need to ship with the production bundle.

### Registry Dependencies

The **`registryDependencies`** array (lines 53-59) defines relationships between registry items themselves. This array can contain:

- **Component names** for internal shadcn/ui dependencies (e.g., a "button" component depending on an "icon" component)
- **URLs** for external registry items hosted outside the main shadcn/ui repository

## How the Component Registry Item Schema Validates Dependencies

When a component is fetched, the schema validation ensures dependency integrity.

The `getRegistryItem` function in [`apps/v4/lib/registry.ts`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/lib/registry.ts) loads registry items and validates them against `registryItemSchema`. This validation occurs at lines 31-36 of the registry implementation, where the function checks that any present dependency arrays conform to the expected string array format defined in the JSON schema.

If validation passes, the dependency fields are retained verbatim in the returned object, allowing build tools and CLI commands to access the raw dependency data for automatic installation.

## Practical Examples of Defining Component Dependencies

### Basic Registry Item with Dependencies

Here's a minimal component definition that declares both NPM and registry dependencies:

```json
{
  "name": "alert",
  "type": "registry:component",
  "title": "Alert",
  "description": "A dismissible alert component.",
  "dependencies": ["react-hot-toast"],
  "registryDependencies": ["button", "icon"]
}

```

This configuration instructs the CLI to install `react-hot-toast` from NPM while also ensuring the local `button` and `icon` components are present.

### Accessing Dependencies Programmatically

When building tooling around the registry, you can extract dependency information using the registry library:

```typescript
import { getRegistryItem } from '@/lib/registry'

async function installComponent(name: string, style: string) {
  const item = await getRegistryItem(name, style)

  // Runtime NPM packages to install
  const npmDeps = item?.dependencies ?? []

  // Other registry items required by this component
  const registryDeps = item?.registryDependencies ?? []

  console.log('Install NPM deps:', npmDeps)
  console.log('Pull registry items:', registryDeps)
}

```

The `getRegistryItem` function returns a validated object containing all three dependency arrays, enabling automated resolution and installation workflows.

### Resolving Registry Dependencies Recursively

For components that depend on other components, you may need to resolve the entire dependency tree:

```typescript
async function resolveAll(name: string, style: string) {
  const item = await getRegistryItem(name, style)

  // Recursively fetch all registry dependencies
  const prerequisites = await Promise.all(
    (item?.registryDependencies ?? []).map(dep => getRegistryItem(dep, style))
  )

  return { item, prerequisites }
}

```

This pattern ensures that installing a complex component automatically pulls in all required sibling components defined in the `registryDependencies` array.

## Summary

The component registry item schema provides a structured, machine-readable format for declaring component requirements through three distinct mechanisms:

- **`dependencies`** specifies runtime NPM packages required for production use
- **`devDependencies`** lists development-only tools and libraries
- **`registryDependencies`** defines relationships to other registry items, enabling component composition

These fields are validated against the JSON schema at [`apps/v4/public/schema/registry-item.json`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/public/schema/registry-item.json) and processed by the `getRegistryItem` function in [`apps/v4/lib/registry.ts`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/lib/registry.ts), ensuring that dependency declarations are both syntactically correct and programmatically accessible.

## Frequently Asked Questions

### What is the component registry item schema in shadcn/ui?

The component registry item schema is a JSON schema located at [`apps/v4/public/schema/registry-item.json`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/public/schema/registry-item.json) that defines the structure and metadata for components in the shadcn/ui registry. It specifies required fields like `name` and `type`, along with optional dependency arrays that declare what a component needs to function.

### How do registryDependencies differ from regular dependencies?

While the `dependencies` field lists external NPM packages required at runtime, `registryDependencies` references other items within the shadcn/ui registry itself. These can be internal component names like `"button"` or `"icon"`, or URLs pointing to external registries, enabling components to compose functionality from existing registry items rather than duplicating code.

### Where does validation of the component registry item schema occur?

Validation occurs in the `getRegistryItem` function within [`apps/v4/lib/registry.ts`](https://github.com/shadcn-ui/ui/blob/main/apps/v4/lib/registry.ts), specifically around lines 31-36. This function fetches the registry item data and validates it against `registryItemSchema`, ensuring that all fields—including the three dependency arrays—conform to the expected types defined in the JSON schema before the data is used by CLI tools or build systems.

### Can a component have all three dependency types simultaneously?

Yes, a single registry item can declare `dependencies`, `devDependencies`, and `registryDependencies` simultaneously. For example, a complex component might need runtime libraries like `clsx` (dependencies), TypeScript types for development (devDependencies), and base components like `button` or `card` from the registry (registryDependencies) to function correctly.