Components.json

lastmod 2026-01-05created 2026-01-053 edits

The components.json file is the core file that holds the configuration of a shadcn/ui project. The CLI uses it to understand the project structure and generate customized components.

Overview

• Purpose: defines the project structure, styling approach, import paths, etc.
• Required: only when using the CLI (not needed for the copy & paste approach)
• How to create: initialize with the pnpm dlx shadcn@latest init command
• Schema: https://ui.shadcn.com/schema.json

Full structure example

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide",
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/{name}.json"
  }
}

Main settings

$schema

• Type: string
• Description: JSON schema reference URL
• Function: supports IDE autocompletion and validation
• Default: "https://ui.shadcn.com/schema.json"

{
  "$schema": "https://ui.shadcn.com/schema.json"
}

style

• Type: "default" | "new-york"
• Description: visual style variant of the components
• Important: cannot be changed after initialization
• Recommended: "new-york" (the default style is deprecated)

{
  "style": "new-york"
}

rsc

• Type: boolean
• Description: whether to use React Server Components
• Function: when true, automatically adds the "use client" directive where needed
• Recommended: true when using the Next.js 13+ App Router

{
  "rsc": true
}

tsx

• Type: boolean
• Description: whether to use TypeScript
• Function:
  • true: includes the .tsx extension and type definitions
  • false: generates JavaScript components with the .jsx extension
• Recommended: true (better type safety and developer experience)

{
  "tsx": true
}

Tailwind CSS settings

The tailwind object handles the Tailwind CSS integration settings.

tailwind.config

• Type: string
• Description: path to the Tailwind configuration file
• Note: set to an empty string when using Tailwind CSS v4

{
  "tailwind": {
    "config": "tailwind.config.js"
  }
}

tailwind.css

• Type: string
• Description: path to the global CSS file that imports Tailwind
• Function: the CLI adds CSS custom properties and base styles

{
  "tailwind": {
    "css": "styles/global.css"
  }
}

tailwind.baseColor

• Type: "gray" | "neutral" | "slate" | "stone" | "zinc"
• Description: base neutral color palette
• Affects: the look of borders, muted text, and neutral elements
• Important: cannot be changed after initialization

{
  "tailwind": {
    "baseColor": "slate"
  }
}

tailwind.cssVariables

• Type: boolean
• Description: chooses how theming is implemented
• Options:
  • true: use CSS custom properties (variables) - easy theme customization
  • false: use Tailwind utility classes directly
• Recommended: true (dynamic theme switching and better maintainability)

{
  "tailwind": {
    "cssVariables": true
  }
}

tailwind.prefix

• Type: string
• Description: prefix for Tailwind class names
• Purpose: prevents class name collisions with existing projects
• Example: setting "tw-" gives forms like tw-flex, tw-p-4

{
  "tailwind": {
    "prefix": "tw-"
  }
}

Path aliases (Aliases)

The aliases object defines import path mappings. It works together with the path settings in tsconfig.json or jsconfig.json.

Important: when using a src directory, it must be included in paths in tsconfig.json.

aliases.components

• Type: string
• Description: import alias for the components directory
• Default: "@/components"

{
  "aliases": {
    "components": "@/components"
  }
}

aliases.utils

• Type: string
• Description: import alias for utility functions
• Example: the cn helper function, etc.
• Default: "@/lib/utils"

{
  "aliases": {
    "utils": "@/lib/utils"
  }
}

aliases.ui

• Type: string
• Description: install location for UI components
• Important: the CLI uses this value to decide where to place UI components
• Default: "@/components/ui"

{
  "aliases": {
    "ui": "@/components/ui"
  }
}

aliases.lib

• Type: string
• Description: import alias for library functions
• Example: format-date, generate-id, etc.
• Default: "@/lib"

{
  "aliases": {
    "lib": "@/lib"
  }
}

aliases.hooks

• Type: string
• Description: import alias for custom hooks
• Example: use-media-query, use-toast, etc.
• Default: "@/hooks"

{
  "aliases": {
    "hooks": "@/hooks"
  }
}

Icon library

iconLibrary

• Type: string
• Description: the icon library to use
• Default: "lucide"
• Supported libraries: lucide-react

{
  "iconLibrary": "lucide"
}

Registry settings

With the registries setting you can install components from multiple sources.

Basic structure

{
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/{name}.json",
    "@internal": {
      "url": "https://internal.company.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${COMPANY_TOKEN}"
      },
      "params": {
        "team": "frontend",
        "version": "${REGISTRY_VERSION}"
      }
    }
  }
}

Usage examples

# 공개 레지스트리에서 설치
npx shadcn@latest add @v0/dashboard

# 인증이 필요한 프라이빗 레지스트리에서 설치
npx shadcn@latest add @company/button

# 여러 소스에서 동시 설치
npx shadcn@latest add @acme/header @internal/auth-utils

Registry configuration options

Complete configuration examples

Next.js + TypeScript + CSS Variables

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Vite + JavaScript + Utility Classes

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": false,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": false,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

CLI commands

Initialization

# components.json 파일 생성 및 초기 설정
pnpm dlx shadcn@latest init

# 옵션 지정
pnpm dlx shadcn@latest init \
  --base-color slate \
  --style new-york \
  --yes

Adding components

# 단일 컴포넌트 추가
npx shadcn@latest add button

# 여러 컴포넌트 동시 추가
npx shadcn@latest add button card dialog

# 모든 컴포넌트 추가
npx shadcn@latest add --all

# 커스텀 경로로 추가
npx shadcn@latest add button --path ./custom/components

Caveats

Settings that cannot be changed

The following settings cannot be changed after initialization:

• style: component style variant
• tailwind.baseColor: base color palette

If you need to change them, you must reinitialize the project.

Path alias settings

The aliases settings must match the paths settings in tsconfig.json or jsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"],
      "@/components/*": ["./components/*"],
      "@/lib/*": ["./lib/*"]
    }
  }
}

Using a src directory

If you use a src directory:

1. Check that it is included in paths in tsconfig.json
2. Use the --src-dir flag with CLI commands
3. Set the aliases paths relative to src

npx shadcn@latest init --src-dir

See also

• Shadcn UI

Favorite site

• components.json - shadcn/ui
• CLI documentation
• Installation guide
• Theming