shadcn CLI

shadcn is a CLI tool and programmatic API for adding UI components to your project. It provides both command-line interface for interactive component management and a powerful programmatic API for fetching and resolving components from registries. The tool features multi-registry support, dependency resolution, code transformation, and AI assistant integration through the Model Context Protocol.

Package Information

• Package Name: shadcn
• Package Type: npm
• Language: TypeScript
• Installation: npm install shadcn or use directly with npx shadcn
• Minimum Node.js Version: 18.x or higher
• Package Manager Support: npm, yarn, pnpm, bun

Quick Start

# Initialize a new project
npx shadcn init

# Add a component
npx shadcn add button

# Add multiple components (non-interactive)
npx shadcn add button card dialog --yes --overwrite

// Programmatic usage
import { getRegistryItems, resolveRegistryItems } from 'shadcn';

// Fetch components
const items = await getRegistryItems(['@shadcn/button', '@shadcn/card']);

// Resolve with dependencies
const resolved = await resolveRegistryItems(['@shadcn/button']);

See Quick Start Guide for detailed setup instructions.

Core Concepts

Registry System

Multi-registry support with namespace-based and URL-based registries. Supports HTTP caching, authentication, and dependency resolution.

CLI Commands

12 commands for component management: init, add, search, view, diff, migrate, info, build, mcp, and more.

Programmatic API

TypeScript API for fetching, resolving, and searching components with full type safety.

Code Transformers

Automatic code transformation for framework compatibility (RSC, CSS variables, icon libraries, Tailwind prefixes).

MCP Integration

Model Context Protocol server with 7 specialized tools for AI assistant workflows.

Entry Points

Main API

import {
  getRegistryItems,
  resolveRegistryItems,
  getRegistry,
  getRegistriesConfig,
  getRegistriesIndex,
  getShadcnRegistryIndex,
  getRegistryStyles,
  getRegistryIcons,
  getRegistryBaseColors,
  getRegistryBaseColor,
  getPresets,
  getPreset
} from 'shadcn';

Registry Module (with errors)

import {
  getRegistryItems,
  searchRegistries,
  RegistryError,
  RegistryNotFoundError,
  RegistryNotConfiguredError,
  ConfigMissingError
  // ... more error classes
} from 'shadcn/registry';

Schemas

import {
  registryItemSchema,
  configSchema,
  registryConfigSchema,
  type RegistryItem,
  type Config
} from 'shadcn/schema';

Transformers

import {
  transformStyle,
  transformIcons,
  transformMenu,
  transformRender,
  createStyleMap
} from 'shadcn/utils';

Icon Libraries

import { iconLibraries, type IconLibraryName } from 'shadcn/icons';

MCP Server

import { server } from 'shadcn/mcp';

Quick Reference

CLI Commands

See CLI Commands Reference for complete documentation.

Core API Functions

See Registry API Reference for complete API documentation.

Error Classes

See Error Handling for complete error documentation.

Architecture Overview

shadcn is built around several key components:

• CLI Layer: Command-line interface built with Commander.js
• Registry System: Multi-registry support with HTTP caching and authentication
• Validation Layer: Comprehensive Zod schemas for runtime validation
• Transformation Pipeline: Code transformers for framework compatibility
• MCP Integration: Model Context Protocol server for AI assistants
• Configuration Management: Cosmiconfig-based configuration discovery

Documentation Structure

Guides

• Quick Start - Getting started with shadcn

Examples

• Real-World Scenarios - Comprehensive usage examples and agent integration patterns
• Edge Cases - Advanced scenarios and error handling

Reference

• CLI Commands - Complete CLI command documentation
• Registry API - Programmatic API reference
• Schemas and Validation - Configuration and validation schemas
• Code Transformers - Code transformation utilities
• Model Context Protocol - MCP server integration

Common Workflows

Adding Components Programmatically

import { resolveRegistryItems } from 'shadcn';
import { writeFile, mkdir } from 'fs/promises';

const resolved = await resolveRegistryItems(['@shadcn/button']);
// Install dependencies, write files, update configs

See Real-World Scenarios for complete examples.

Error Handling

import { getRegistryItems, RegistryNotFoundError, ConfigMissingError } from 'shadcn/registry';

try {
  const items = await getRegistryItems(['@shadcn/button']);
} catch (error) {
  if (error instanceof ConfigMissingError) {
    // Project not initialized
  } else if (error instanceof RegistryNotFoundError) {
    // Item not found
  }
}

See Edge Cases for comprehensive error handling patterns.

Configuration Discovery

import { getRegistriesConfig } from 'shadcn';
import { findUp } from 'find-up';

const configPath = await findUp('components.json', { cwd: process.cwd() });
const { registries } = await getRegistriesConfig(dirname(configPath));

Icon Libraries

Supported icon libraries: Lucide, Tabler, HugeIcons, and Phosphor Icons.

import { iconLibraries, type IconLibraryName } from 'shadcn/icons';

type IconLibraryName = "lucide" | "tabler" | "hugeicons" | "phosphor"

Deprecated APIs

The following functions are deprecated:

• resolveTree → Use resolveRegistryItems
• fetchTree → Use getRegistryItems with resolved dependencies
• getItemTargetPath → Use config.resolvedPaths directly

Next Steps

• Read the Quick Start Guide for setup instructions
• Explore Real-World Scenarios for usage examples
• Review CLI Commands Reference for command details
• Check Registry API Reference for programmatic usage