Components.json

components.json 파일은 shadcn/ui 프로젝트의 설정을 담고 있는 핵심 파일입니다. CLI가 프로젝트 구조를 이해하고 커스터마이징된 컴포넌트를 생성하는데 사용됩니다.

개요

• 목적: 프로젝트 구조, 스타일링 방식, 임포트 경로 등을 정의
• 필수 여부: CLI를 사용할 때만 필요 (copy & paste 방식은 불필요)
• 생성 방법: pnpm dlx shadcn@latest init 명령어로 초기화
• 스키마: https://ui.shadcn.com/schema.json

전체 구조 예시

{
  "$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"
  }
}

주요 설정 항목

$schema

• 타입: string
• 설명: JSON 스키마 참조 URL
• 기능: IDE의 자동완성 및 유효성 검증 지원
• 기본값: "https://ui.shadcn.com/schema.json"

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

style

• 타입: "default" | "new-york"
• 설명: 컴포넌트의 시각적 스타일 변형
• 중요: 초기화 이후 변경 불가
• 권장: "new-york" (default 스타일은 deprecated)

{
  "style": "new-york"
}

rsc

• 타입: boolean
• 설명: React Server Components 사용 여부
• 기능: true일 때 필요한 경우 "use client" 지시어 자동 추가
• 권장: Next.js 13+ App Router 사용 시 true

{
  "rsc": true
}

tsx

• 타입: boolean
• 설명: TypeScript 사용 여부
• 기능:
  • true: .tsx 확장자 및 타입 정의 포함
  • false: .jsx 확장자로 JavaScript 컴포넌트 생성
• 권장: true (타입 안정성 및 개발자 경험 향상)

{
  "tsx": true
}

Tailwind CSS 설정

tailwind 객체는 Tailwind CSS 통합 설정을 담당합니다.

tailwind.config

• 타입: string
• 설명: Tailwind 설정 파일 경로
• 참고: Tailwind CSS v4 사용 시 빈 문자열로 설정

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

tailwind.css

• 타입: string
• 설명: Tailwind를 import하는 전역 CSS 파일 경로
• 기능: CLI가 CSS 커스텀 속성 및 기본 스타일 추가

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

tailwind.baseColor

• 타입: "gray" | "neutral" | "slate" | "stone" | "zinc"
• 설명: 기본 중립 색상 팔레트
• 영향: 테두리, 음영 처리된 텍스트 및 중립적 요소의 외관
• 중요: 초기화 이후 변경 불가

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

tailwind.cssVariables

• 타입: boolean
• 설명: 테마 구현 방식 선택
• 옵션:
  • true: CSS 커스텀 속성(변수) 사용 - 테마 커스터마이징 용이
  • false: Tailwind 유틸리티 클래스 직접 사용
• 권장: true (동적 테마 변경 및 유지보수성 향상)

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

tailwind.prefix

• 타입: string
• 설명: Tailwind 클래스명 접두사
• 목적: 기존 프로젝트와의 클래스명 충돌 방지
• 예시: "tw-" 설정 시 tw-flex, tw-p-4 형태

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

경로 별칭 (Aliases)

aliases 객체는 임포트 경로 매핑을 정의합니다. tsconfig.json 또는 jsconfig.json의 경로 설정과 함께 작동합니다.

중요: src 디렉토리 사용 시 tsconfig.json의 paths에 반드시 포함되어야 합니다.

aliases.components

• 타입: string
• 설명: 컴포넌트 디렉토리 임포트 별칭
• 기본값: "@/components"

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

aliases.utils

• 타입: string
• 설명: 유틸리티 함수 임포트 별칭
• 예시: cn 헬퍼 함수 등
• 기본값: "@/lib/utils"

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

aliases.ui

• 타입: string
• 설명: UI 컴포넌트 설치 위치
• 중요: CLI가 이 값을 사용하여 UI 컴포넌트 배치 위치 결정
• 기본값: "@/components/ui"

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

aliases.lib

• 타입: string
• 설명: 라이브러리 함수 임포트 별칭
• 예시: format-date, generate-id 등
• 기본값: "@/lib"

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

aliases.hooks

• 타입: string
• 설명: 커스텀 훅 임포트 별칭
• 예시: use-media-query, use-toast 등
• 기본값: "@/hooks"

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

아이콘 라이브러리

iconLibrary

• 타입: string
• 설명: 사용할 아이콘 라이브러리
• 기본값: "lucide"
• 지원 라이브러리: lucide-react

{
  "iconLibrary": "lucide"
}

레지스트리 설정

registries 설정을 통해 다중 소스에서 컴포넌트를 설치할 수 있습니다.

기본 구조

{
  "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}"
      }
    }
  }
}

사용 예시

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

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

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

레지스트리 설정 옵션

완전한 설정 예시

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 명령어

초기화

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

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

컴포넌트 추가

# 단일 컴포넌트 추가
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

주의사항

변경 불가능한 설정

다음 설정들은 초기화 이후 변경할 수 없습니다:

• style: 컴포넌트 스타일 변형
• tailwind.baseColor: 기본 색상 팔레트

변경이 필요한 경우 프로젝트를 재초기화해야 합니다.

경로 별칭 설정

aliases 설정은 반드시 tsconfig.json 또는 jsconfig.json의 paths 설정과 일치해야 합니다:

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

src 디렉토리 사용

src 디렉토리를 사용하는 경우:

1. tsconfig.json의 paths에 포함되어 있는지 확인
2. CLI 명령어에 --src-dir 플래그 사용
3. aliases 경로를 src 기준으로 설정

npx shadcn@latest init --src-dir

See also

• Shadcn UI

Favorite site

• components.json - shadcn/ui
• CLI 문서
• 설치 가이드
• 테마 설정