Shadcn 세팅

🧩 Reference

• shadcn/ui: Tailwind 기반의 복사 가능한 컴포넌트 라이브러리
• @types/node: Vite 설정에서 Node.js 타입 지원
• shadcn/ui 공식 문서

shadcn/ui를 선택한 이유

일반적인 UI 라이브러리는 npm install로 설치하고 사용한다.
하지만 shadcn/ui는 다르다. 컴포넌트 코드를 프로젝트에 직접 복사해서 사용하는 방식이다.

이 방식의 장점:

• 컴포넌트 코드를 완전히 소유하고 자유롭게 수정 가능
• 필요한 컴포넌트만 선택해서 추가 (번들 크기 최적화)
• Tailwind 기반이라 프로젝트 디자인 시스템과 통합이 쉬움

shadcn/ui vs 일반 UI 라이브러리

	shadcn/ui	MUI / Ant Design
설치 방식	컴포넌트 코드 복사	npm 패키지
소유권	프로젝트 내 코드	외부 라이브러리
커스터마이징	완전 자유	제한적 (theme 등)
번들 크기	사용한 만큼만	전체 패키지
스타일	Tailwind	자체 스타일 시스템
업데이트	선택적	패키지 의존성

설치 및 초기 설정

이 과정은 Vite + React + TypeScript + Tailwind 환경을 기준으로 한다.

1. shadcn/ui 초기화

npx shadcn@latest init

2. Tailwind 연결 (index.css)

@import 'tailwindcss';

3. Path Alias 설정

// tsconfig.json

{
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.node.json"
    }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

// tsconfig.app.json

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

4. @types/node 설치

npm install -D @types/node

왜 필요한가?

Vite 설정 파일(vite.config.ts)에서 path alias 설정을 할 때 Node.js의 path 모듈을 사용한다.

// vite.config.ts
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

TypeScript가 path, __dirname 같은 Node.js 전역 타입을 인식하려면 @types/node가 필요하다.

컴포넌트 추가 방법

shadcn/ui는 필요한 컴포넌트만 선택해서 추가하는 방식이다.

1. 컴포넌트 추가

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

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

2. 생성된 컴포넌트 사용

import { Button } from '@/components/ui/button';

export function App() {
  return <Button>Click me</Button>;
}

3. 커스터마이징

컴포넌트 코드가 src/components/ui/에 직접 있으므로 자유롭게 수정 가능하다.

export function Button({ className, children, ...props }) {
  return (
    <button
      className={cn('px-4 py-2 rounded-md bg-blue-500 text-white', className)}
      {...props}
    >
      {children}
    </button>
  );
}

---

💡 정리

• shadcn/ui는 컴포넌트를 npm 패키지가 아닌 코드로 복사해서 사용한다.
• Vite + TypeScript 환경에서는 @types/node 설치가 필요하다.
• 필요한 컴포넌트만 선택적으로 추가할 수 있다.
• 컴포넌트 코드를 직접 소유하므로 커스터마이징이 자유롭다.
• Tailwind 기반이라 프로젝트 스타일과 통합이 쉽다.
• 실제 UI 컴포넌트는 필요할 때마다 추가하며 점진적으로 확장한다.