shadcn/ui (1)

shadcn/ui

shadcn/ui는 UI 라이브러리, 더 정확한 표현은 “복사해서 내 프로젝트에 넣어 사용하는 컴포넌트 컬렉션”입니다.

• npm 패키지를 설치해서 사용하는 구조가 아님
• 대신 컴포넌트 소스코드 자체가 프로젝트 내부로 복사됨
• 그래서 자유롭게 수정 가능, 커스텀 가능
• 디자인 시스템 구축에 최적화된 방식

 

일반 UI 라이브러리는 테마나 스타일이 이미 고정돼 있어서 완전히 구조를 바꿀 때 한계가 있습니다.
반면 shadcn/ui는 소스코드를 가져와서 내 프로젝트 기준으로 마음대로 바꿀 수 있기 때문에

• 컴포넌트 스타일 완전 재정의 가능
• UI·UX를 디자인 시스템에 100% 맞출 수 있음
• 불필요한 컴포넌트 삭제 가능
• 팀 내 UI 코드 일관성 유지가 쉬움

 

 

---

 

 

기존 UI 라이브러리와 다른 점

기존 UI 라이브러리(MUI / Chakra / AntD) 개요

일반적으로 많이 쓰는 UI 라이브러리들은 모두 완성된 컴포넌트를 패키지 형태로 제공합니다.

• MUI (Material UI): 테마 기반, 매우 많은 컴포넌트, 구글 Material Design 철학을 따름
• Chakra UI: 직관적 API, Styled System 기반, 커스터마이징 쉬움
• Ant Design: 엔터프라이즈 UI에 강함, 디자인이 뚜렷하고 무겁지만 완성도가 높음

위 라이브러리들의 공통점

• 이미 완성된 컴포넌트를 그대로 사용
• 스타일 시스템이 내부적으로 고정되어 있음
• 디자인 토큰 변경 범위가 제한적
• 원하는 형태로 완전히 뜯어고치기가 어려움

특히 디자인팀 또는 브랜드 가이드가 있는 조직에서는 라이브러리 스타일과 맞추기 힘들어 커스텀이 커짐.

 

 

shadcn/ui : "라이브러리가 아니라 컴포넌트 컬렉션이다"

shadcn/ui는 npm으로 가져다 쓰는 UI 패키지가 아닙니다.

• 설치하면 소스코드가 그대로 내 프로젝트에 들어오고
• 마음대로 수정하고
• 폴더 구조도 바꿀 수 있고
• 스타일도 완전히 덮어씌울 수 있음

이 점이 기존 UI 라이브러리와 완전히 다릅니다.

 

---

 

장점

• 디자인 시스템 커스텀에 최강
• 프로젝트 코드베이스와 완전히 통합됨
• 패키지 업데이트에 휘둘리지 않음 (내가 관리)
• Tailwind 기반으로 확장성 높음

단점 

• 스스로 유지보수해야 한다
• 컴포넌트 수가 많아지면 관리 비용 증가
• "그냥 가져다 쓰면 된다"는 느낌의 간편함은 적다

 

---

 

 

Next.js + shadcn/ui 설치 

1) 설치

프로젝트 루트에서 아래 명령어 실행

npx shadcn@latest init

 

• Tailwind 기본 세팅
• 글로벌 스타일(global.css)
• 라디컬 UI 토큰(radix variables)
• shadcn/ui 컴포넌트 구조(src/components/ui)

설치 후 프로젝트 루트에 다음 파일이 생깁니다

components.json

• 이 파일이 shadcn/ui 설정의 핵심입니다.

 

2) 컴포넌트 추가

shadcn/ui는 필요한 UI만 골라서 설치할 수 있습니다.

 

예: Button 추가

npx shadcn@latest add button

 

Dialog 추가:

npx shadcn@latest add dialog

 

Toast 추가:

npx shadcn@latest add toast

 

컴포넌트를 추가하면

• src/components/ui/button.tsx
• src/components/ui/dialog.tsx
• ...

처럼 프로젝트 내부에 소스코드 형태로 복사됩니다.

원하면 바로 수정 가능합니다.

 

alias & tsconfig 경로 설정

shadcn/ui를 쓰는 프로젝트는 보통 다음 alias를 사용합니다:

tsconfig.json 예시

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

Next.js에서는 기본적으로 아래 alias도 지원합니다:

• @/components/...
• @/app/...
• @/lib/...

shadcn/ui 컴포넌트도 이 패스를 기준으로 import되기 때문에 반드시 설정해야 합니다.