Frontend

shadcn/ui 완벽 가이드 — 복붙으로 만드는 UI

한 줄 요약: shadcn/ui는 컴포넌트 라이브러리가 아니라 '복붙 가능한 코드 모음'으로, 소유권이 개발자에게 있어 자유롭게 수정할 수 있다. Tailwind CSS + Radix UI를 기반으로 한 shadcn/ui는 npm 패키지가 아니라 CLI로 코드를 프로젝트에 직접 복사한다. shadcn/ui 는 일반적인 npm 패키지가 아닙니다. 컴포넌트 코드를 내 프로젝트에 직접 복사하는 방식입니다.

by Lee발행: 2026-04-09

한 줄 요약: shadcn/ui는 컴포넌트 라이브러리가 아니라 '복붙 가능한 코드 모음'으로, 소유권이 개발자에게 있어 자유롭게 수정할 수 있다.

Tailwind CSS + Radix UI를 기반으로 한 shadcn/ui는 npm 패키지가 아니라 CLI로 코드를 프로젝트에 직접 복사한다. 이 접근법의 장단점과 실전 활용 패턴을 정리한다.

shadcn/ui란?

shadcn/ui는 일반적인 npm 패키지가 아닙니다. 컴포넌트 코드를 내 프로젝트에 직접 복사하는 방식입니다. Radix UI + Tailwind CSS 기반이며, 모든 코드를 직접 수정할 수 있습니다.

shadcn/ui의 핵심 철학은 '코드 소유권'이다. npx shadcn-ui@latest add button을 실행하면 Button 컴포넌트의 전체 소스코드가 components/ui/button.tsx에 복사된다. npm 의존성이 아니므로 업데이트에 의한 breaking change가 없고, 프로젝트 요구에 맞게 자유롭게 수정할 수 있다.

shadcn/ui 초기 설정
# 프로젝트 초기화
npx shadcn-ui@latest init

# 컴포넌트 추가
npx shadcn-ui@latest add button card dialog
npx shadcn-ui@latest add form input label
npx shadcn-ui@latest add table dropdown-menu

내부적으로 Radix UI(접근성 보장된 headless 컴포넌트), Tailwind CSS(스타일링), class-variance-authority(CVA)(variant 관리)를 사용한다. 이 조합이 접근성 + 스타일 커스터마이징 + variant 관리를 모두 해결한다.

시작하기

npx shadcn@latest init으로 초기화 → npx shadcn@latest add button으로 필요한 컴포넌트 추가. 추가된 코드는 components/ui/ 폴더에 저장됩니다.

v0와의 시너지

Vercel의 v0에서 생성된 UI는 shadcn/ui 기반입니다. v0에서 디자인 → 코드 복사 → 내 프로젝트에 적용하는 워크플로우가 매우 매끄럽습니다.

커스터마이징 실전 패턴

테마 변경: globals.css의 CSS 변수를 수정하면 전체 테마가 변경된다. --primary, --secondary, --radius 등을 프로젝트 디자인 시스템에 맞게 설정한다. Variant 확장: CVA의 variants 객체에 새로운 variant를 추가하면 <Button variant='custom'>처럼 사용할 수 있다.

다크 모드: components.json에서 cssVariables: true로 설정하면 .dark 클래스 기반 다크 모드가 자동 적용된다. next-themes 라이브러리와 조합하면 시스템 설정 연동까지 간단히 구현된다.

팁: shadcn/ui 공식 사이트의 'Themes' 페이지에서 색상 조합을 미리보고 CSS 변수 코드를 복사할 수 있다. 디자이너와 협업 시 이 도구로 빠르게 프로토타입을 만들어 확인하라.

1인 개발자 관점에서 이 주제가 왜 중요한가

이 글의 주제(shadcn/ui 완벽 가이드 — 복붙으로 만드는 UI)를 다룰 때 저는 Next.js + Vercel 조합으로 12개 사이트를 운영하면서 겪은 실측 이슈 관점에서 봅니다. 단순히 새 기능을 소개하는 입장이 아니라, 12개 한국어 사이트를 1인으로 운영하면서 매일 클로드 코드를 켜두고 작업하는 입장이라 의사결정의 기준이 다소 좁고 실용적인 편입니다. 신기술이 출시될 때마다 곧바로 도입하기보다는 우선 한두 사이트에 시범 도입해 두고, 운영 부담이 늘지 않는지 며칠 지켜본 뒤 전체 확산을 결정하는 식입니다.

가장 자주 보는 변수는 한국어 응답 품질의 미세한 한계, 그리고 버셀 무료 티어 한도 vs 유료 전환 시점입니다. 두 변수는 신기술을 도입할지 말지 결정할 때 거의 매번 영향을 줍니다. 글의 본문은 위의 두 축을 직접 명시하지는 않지만, 본문에서 다루는 항목을 이 축에 비춰 보시면 본인 환경에 맞는지 빠르게 판단할 수 있습니다. 특히 12개 사이트를 동시에 운영할 때 변수 분리 비용 같은 운영 변수는 도구 자체 성능보다 더 큰 영향을 주는 경우가 많기 때문에 본문 비교표를 볼 때 같이 떠올리시면 좋습니다.

한 가지 더 강조하면, Frontend 영역의 글을 읽을 때 저는 본문이 다루는 도구·서비스가 ① 한국 결제 가능 여부 ② 한국어 응답 품질 ③ 종량제 비용의 예측 가능성 ④ 1인 개발자 학습 시간 대비 효과, 네 항목을 모두 충족해야 실제 도입을 결정합니다. 네 항목 중 하나라도 명확하지 않으면 도입을 1~2주 미루는 편이고, 그 사이 같은 카테고리의 다른 글도 확인합니다.

본문의 각 비교·코드·체크리스트는 이 네 항목 중 어느 부분에 영향을 주는지 의식하면서 보시면 더 빠르게 결론에 도달하실 수 있습니다. 본 사이트의 다른 Frontend 글과 함께 보시면 같은 평가 축이 반복되는 것을 확인하실 수 있습니다. 토픽 페이지 또는 같은 카테고리 태그를 따라가시면 동일한 평가 기준이 적용된 글을 한 번에 모아 보실 수 있습니다.

본인 환경에 적용하기 전 확인할 체크포인트

본문의 내용을 본인 환경에 적용하기 전에 다음 항목을 빠르게 확인하시면 도입 실패 가능성을 줄일 수 있습니다.

공식 문서 버전 일치 — 본문 작성 시점과 현재 배포 버전이 다른 경우, 같은 명령어가 다르게 동작할 수 있습니다.
한국 결제·환율 검증 — 카드 결제, 부가가치세 처리, 원화 환산 시점에 따라 실제 청구액이 본문 예시와 다를 수 있습니다.
기존 스택과의 호환성 — Next.js·Vercel·Supabase 같은 기본 스택과 충돌이 없는지 패키지 의존성을 먼저 확인하세요.
롤백 절차 사전 정리 — 도입 후 문제가 생겼을 때 1회 명령으로 이전 상태로 되돌릴 수 있는 절차를 도입 전에 메모해 두시면 운영 부담이 크게 줄어듭니다.

위 네 항목을 모두 통과하면 보통 1~2시간 내에 도입을 마칠 수 있고, 통과하지 못한 항목이 있다면 그 항목을 우선 해결한 뒤 다시 시작하는 것이 효율적입니다.

자주 묻는 질문

실무에서 처음 도입할 때 가장 먼저 확인할 것은 무엇인가요?

shadcn/ui는 npm 패키지가 아니라 코드를 직접 복사하는 방식이라, 가장 먼저 확인할 것은 프로젝트에 Tailwind CSS가 이미 설정되어 있는지와 components.json이 가리키는 경로입니다. npx shadcn@latest init 단계에서 별칭(@/components) 경로, CSS 변수 사용 여부(cssVariables), 다크 모드 방식을 한 번 정하면 이후 모든 add 명령이 그 설정을 따라가기 때문입니다. 저는 처음에 이 init 설정을 대충 넘겼다가 추가한 컴포넌트들이 엉뚱한 폴더에 깔려 다시 잡은 적이 있어서, init의 질문 답변만큼은 꼼꼼히 보시길 권합니다.

가장 자주 발생하는 실수나 함정은 무엇인가요?

가장 흔한 함정은 복사해 온 컴포넌트를 npm 패키지처럼 다루는 것입니다. shadcn/ui는 코드 소유권이 내 프로젝트에 넘어오는 구조라, 일단 add 한 button.tsx를 내가 수정하면 그 뒤로는 자동 업데이트가 없습니다. 공식 저장소에서 컴포넌트가 개선돼도 내 파일은 그대로이니, 직접 수정한 컴포넌트는 변경 이력을 따로 메모해 두지 않으면 나중에 어디를 손봤는지 추적이 어렵습니다. 또 하나는 globals.css의 CSS 변수를 건드리지 않은 채 컴포넌트마다 Tailwind 클래스를 덧붙여 색을 맞추는 패턴인데, 이렇게 하면 테마를 한 번에 바꿀 수 없어집니다. 색은 반드시 --primary 같은 변수에서 관리하시는 게 좋습니다.

다른 대안과 비교했을 때 어떤 상황에 적합한가요?

shadcn/ui는 디자인을 처음부터 내 손으로 다듬고 싶은 프로젝트, 특히 Next.js·Tailwind 기반에 v0로 화면을 빠르게 뽑아 쓰는 워크플로우에 잘 맞습니다. 코드가 내 저장소로 들어오기 때문에 디자인 시스템을 직접 소유하려는 1인 개발자나 작은 팀에 적합합니다. 반대로 컴포넌트를 npm으로 받아 버전만 올리며 손 안 대고 쓰고 싶거나, Tailwind를 안 쓰고 Material UI·Mantine처럼 완성형 라이브러리의 기본 디자인을 그대로 쓰려는 경우, 또는 Vue·Svelte 단독 프로젝트라면 shadcn/ui보다 그쪽 생태계 전용 라이브러리가 더 편합니다. 즉 커스터마이징 자유도가 필요하면 shadcn/ui, 손 안 대고 즉시 쓰는 일관성이 필요하면 전통적 패키지형이 낫습니다.

더 깊게 공부하려면 어떤 자료를 보면 좋을까요?

두 갈래로 파시길 권합니다. 첫째는 shadcn/ui 공식 문서(ui.shadcn.com)의 Theming과 components.json 항목, 그리고 Themes 페이지입니다. CSS 변수로 테마를 통째로 바꾸는 방식이 여기 가장 잘 정리돼 있습니다. 둘째는 shadcn/ui가 의존하는 두 토대인 Radix UI 공식 문서와 class-variance-authority(CVA) README입니다. Radix의 headless·접근성 모델과 CVA의 variant 정의 방식을 알아야 add 해 온 컴포넌트를 자유롭게 확장할 수 있습니다. 키워드로는 'Radix primitives', 'CVA variants', 'Tailwind CSS variables', 'next-themes 다크모드'를 검색하시면 됩니다.

shadcn/ui 완벽 가이드, 한 줄로 정리하면 어떻게 되나요?

shadcn/ui는 설치해서 import 하는 npm 컴포넌트 라이브러리가 아니라, CLI로 컴포넌트 소스코드를 내 프로젝트에 직접 복사해 소유권을 가져오는 방식입니다. Radix UI로 접근성을, Tailwind CSS로 스타일을, CVA로 variant를 처리하며, 색은 globals.css의 CSS 변수에서 한 번에 관리합니다. 코드가 내 것이라 자유롭게 고칠 수 있지만 그만큼 자동 업데이트가 없어 수정 이력은 직접 챙겨야 한다는 점이 핵심입니다.

shadcnui컴포넌트tailwindradix