Shadcn: Shadcn TailwindCSS 세팅

Shadcn이란?

🌐shadcn/ui

기본적인 UI 라이브러리와 Shadcn의 큰 차이는 코드가 어디에 저장되는가? 이다.

차이점

일반 라이브러리(MUI, AntDesign 등)

• node_modules 안에 들어있음
• 사용자는 그저 import { Button } from 'mui'로 불러 쓸 뿐 버튼 내부의 로직이나 스타일을 직접 수정하려면 복잡한 방법을 거쳐야한다.

Shadcn

• npx shadcn add button을 입력하면 버튼 전체 소스 코드가 내 프로젝트의 예) src/components/ui/button.tsx에 파일로 복사가 되어 들어온다.
• 이렇게 복사가 된 파일은 해당 프로젝트의 소유권이 된다. 직접 커스텀 및 조작이 용이하다.

---

기능과 디자인의 분리

"그럼 코드를 일일이 다 짜주는 건가?" 싶겠지만 shadcn은 바닥부터 만드는 건 아니다. Radix UI라는 '뼈대(Headless UI)' 위에 Tailwind CSS라는 '스타일'을 붙여놓은 상태이다.

• Radix UI (뼈대): 접근성(Accessibility), 키보드 조작, 팝업 열고 닫기 같은 복잡한 기능 담당 (눈에 안 보임).
• Tailwind CSS (살): 디자인과 스타일링 담당.
• shadcn (조합기): 이 둘을 조합해서 "바로 쓸 수 있는 코드 파일" 형태로 우리에게 전달해주는 역할을 한다.

---

프로젝트 생성 및 Tailwind CSS 설치

설치

# Tailwind CSS 및 관련 라이브러리 설치
npm install -D tailwindcss postcss autoperfixer

tailwind.config.js 생성

# tailwind.config.js 생성
npx tailwindcss init -p 

또는 

npx tailwindcss init

---

🕵️ 명령어 -p라는 옵션은?

• npx tailwindcss init: tailwind.config.js만 생성
  
• npx tailwindcss init -p: tailwind.config.js와 함께 postcss.config.js를 세트로 생성

Q: PostCSS랑 Autoprefixer는 꼭 설치해야 되나?
A: Tailwind가 작성한 클래스명을 실제 CSS로 변환하고 모든 브라우저에서 디자인이 유지되도록 접두사를 붙여주는 핵심 일꾼들이다. init -p 명령어로 한 번에 생성하는 걸 권장

---

🕵️ TailwindCSS PostCSS Autoprefixer 란?

Tailwind CSS

• 유틸리티 퍼스트(utility-first) CSS 프레임워크

# 무슨기능?
# 미리 만들어진 작은 CSS 클래스들을 조합해서 UI를 만든다
# 직접 CSS 길게 작성하지 않고 클래스만으로 스타일을 구성

<div class="bg-blue-500 text-white p-4 rounded-lg">
  버튼
</div>

- `bg-blue-500` → 배경 파랑
- `text-white` → 글자 흰색
- `p-4` → 패딩
- `rounded-lg` → 둥근 모서리

PostCSS

• CSS를 변환해주는 도구(플랫폼)

# 무슨기능?
# CSS에 여러 플러그인을 적용해 기능을 확장
# 자체적으로 스타일을 제공하는 게 아니라 플러그인을 통해 CSS를 가공하는 역할

- 최신 CSS 문법을 구형 브라우저용으로 변환
- 자동으로 prefix 추가
- CSS 압축
- Tailwind 처리

Autoprefixer

• PostCSS 플러그인 중 하나 브라우저 호환성을 위해 CSS에 자동으로 vendor prefix를 붙여준다.

# 작성 코드
display: flex;

# Autoprefixer 적용 후
display: -webkit-box;
display: -ms-flexbox;
display: flex;

Tailwind CSS → PostCSS 위에서 동작
Autoprefixer → PostCSS 플러그인
PostCSS → CSS 가공 엔진

---

필수 환경 설정

shadcn은 내 프로젝트의 파일을 직접 수정하기 때문에, 경로 별칭(Alias) 설정을 반드시 해줘야 한다.

절대 경로 설정

1. tsconfig.json 수정

경로를 @/로 시작할 수 있도록 compilerOptions 안에 추가한다.

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

2. vite.config.ts 수정

Vite가 @ 기호를 실제 ./src 폴더로 인식하게 설정 (에러 방지를 위해 @types/node를 먼저 설치: npm i -D @types/node)

export default defineConfig({
	plugins: [react()], 
	resolve: { 
		alias: { 
			"@": path.resolve(__dirname, "./src"), 
		}, 
	}, 
})

3. tailwind.config.js 수정

어떤 파일에서 Tailwind 클래스를 사용할지 명시

/** @type {import('tailwindcss').Config} */ 
export default { 
	content: ["./index.html", "./src/**/*.{ts,tsx,js,jsx}"], 
	theme: { extend: {} }, 
	plugins: [],

4. postcss.config.js

Tailwind가 작성한 클래스명을 실제 CSS로 변환하고 모든 브라우저에서 디자인이 유지되도록 하는 설정 부분 체크만 !

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

5. Tailwind CSS의 엔진 켜기

프로젝트의 가장 최상위 엔트리 CSS(또는 SCSS) 파일에 넣어야 한다.

• Vite 프로젝트 기준: 보통 src/index.css 또는 src/main.scss 파일

🕵️ 중요한 기준: main.tsx 또는 App.tsx에서 import "./index.css"와 같이 직접적으로 불러오고 있는 파일에 적용

@tailwind base;
@tailwind components;
@tailwind utilities;

• base: 브라우저마다 제각각인 기본 여백 등을 초기화 이게 제일 밑바닥에 깔려야 함
• components: 버튼이나 카드 같은 덩어리 스타일이 들어감
• utilities: mt-4, text-red-500 처럼 아주 구체적인 속성들이다. 가장 마지막에 와야 내가 클래스로 준 속성이 다른 스타일을 덮어쓰기(Override) 할 수 있다.

6. shadcn/ui 초기화 (Init)

아래 명령어를 입력하면 shadcn이 필요한 유틸리티 파일들을 생성

npx shadcn@latest init

Base color: Which color would you like to use as the base color? 를 결정한다.

• 선택지: Slate, Gray, Zinc, Neutral, Stone
  
• 설명: 프로젝트의 기본 무채색 톤을 결정
  
• 추천: Slate 또는 Zinc.

✔ Writing components.json.
✔ Checking registry.
✔ Updating tailwind.config.ts
✔ Updating CSS variables in src/shared/styles/index.scss
✔ Installing dependencies.
✔ Created 1 file:
  - src/lib/utils.ts

Success! Project initialization completed.
You may now add components.

src/lib/utils.ts 경로에 중복 Tailwind 클래스는 정리해주는 헬퍼 유틸 함수가 생성되는데 그대로 두거나 해당 프로젝트의 폴더구조에 옮기고 components.json에서 경로 수정을 한다.

index.scss에 자동으로 CSS 변수가 생성되는데 나는 따로 관리를 하기 위해 index.scss가 아닌 따로 tailwind.css로 옮겼다.

그리고 이때 lucide-react(아이콘), tailwind-merge, clsx(클래스 합성 유틸) 같은 기본 의존성들이 한꺼번에 설치된다.

---

components.json 상세 속성

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

1. 기본 설정 (Core)

• $schema: 이 파일이 지켜야 할 규격을 정의, VS Code 같은 에디터에서 자동 완성이나 오타 검사를 도와준다.
• style: 컴포넌트의 디자인 스타일 (new-york 또는 default)
  • new-york: 더 작은 폰트와 세밀한 패딩을 가진 현대적인 스타일
• rsc (React Server Components): Next.js의 서버 컴포넌트를 사용할지 여부
• tsx: 생성되는 컴포넌트 파일의 확장자를 .tsx로 할지 결정 TypeScript 사용자라면 당연히 true

2. 테일윈드 설정 (tailwind)

• config: tailwind.config.ts 파일의 위치 CLI가 테마를 업데이트할 때 이 파일을 참조
• css: 가장 중요한 부분 프로젝트의 메인 CSS/SCSS 파일 경로
• baseColor: shadcn이 생성하는 기본 색상 팔레트 (neutral, slate 등)
• cssVariables: 색상을 HSL 값으로 직접 박을지, CSS 변수(--primary 등)로 관리할지 결정
• prefix: Tailwind 클래스 앞에 붙일 접두사 (예: tw-) 보통은 비워둠

3. 라이브러리 및 기타

• iconLibrary: 사용할 아이콘 라이브러리 기본값은 lucide
• rtl (Right-to-Left): 아랍어처럼 오른쪽에서 왼쪽으로 읽는 언어를 지원할지 여부

4. 경로 별칭 (aliases)

컴포넌트가 설치될 '주소'를 정의 tsconfig의 paths 설정과 일치해야 한다.

• components: 직접 만든 컴포넌트가 들어갈 루트 경로입니다 (@/components)
• ui: 핵심 shadcn에서 내려받는 순수 UI 컴포넌트(Button, Input 등)가 저장되는 곳(@/components/ui)
• utils: cn 함수 같은 유틸리티 파일의 위치
• lib, hooks: 각각 공통 라이브러리와 커스텀 훅이 저장될 위치

---

컴포넌트 추가 및 사용

1. 컴포넌트 설치 명령

🌐Components - shadcn/ui

Shadcn의 공식 사이트 - 컴포넌트 검색을 통해 컴포넌트 추가 명령어를 확인하고 추가 명령어를 입력한다.

버튼 컴포넌트

🌐Button - shadcn/ui

npx shadcn@latest add button

🕵️ 특정 컴포넌트를 처음 추가할 때 해당 컴포넌트가 필요한 Radix Ui패키지를 Shadcn이 감지해서 설치해준다.

추가 예시

jaiden-linux@DESKTOP-TPMO2QL:~/projects/test$ npx shadcn@latest add button
✔ Checking registry.
✔ Installing dependencies.
✔ Created 1 file:
  - src/shared/ui/button.tsx

2. cn() 유틸리티 함수

• 역할: clsx와 tailwind-merge를 결합한 함수.
• 장점: 조건부 스타일링을 편하게 하고, Tailwind 클래스 간의 충돌(예: p-2와 p-4가 같이 들어왔을 때)을 똑똑하게 해결해 준다.

// 예시: className을 외부에서 주입받아 합칠 때
<button className={cn("bg-blue-500", className)}>

3. Shadcn 컴포넌트 구조 (Button 예시)

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/shared/lib/utils/styles.util"

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
  {
    variants: {
      variant: {
        default:
          "bg-primary text-primary-foreground shadow hover:bg-primary/90",
        destructive:
          "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
        outline:
          "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
        secondary:
          "bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 rounded-md px-3 text-xs",
        lg: "h-10 rounded-md px-8",
        icon: "h-9 w-9",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button"
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
Button.displayName = "Button"

export { Button, buttonVariants }

---

1. 라이브러리 호출

import * as React from "react"
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/shared/lib/utils/styles.util"

• Slot (Radix UI): 이 버튼을 <a> 태그나 다른 태그로 바꾸고 싶을 때 사용하는 슬롯 (asChild 속성 관련)
• cva (Class Variance Authority): CSS 클래스를 조건부로 관리해주는 핵심 도구 "빨간색 버튼", "큰 버튼" 같은 스타일 옵션을 여기서 정의한다.
• cn: 초기 세팅에 생성되는 머지 유틸 함수 여러 개의 클래스를 충돌 없이 합쳐주는 역할

---

2. 스타일 정의(cva)

shadcn의 디자인 엔진이다.

const buttonVariants = cva( "inline-flex items-center ...", // 기본(공통) 스타일 
	{ 
	variants: { 
		size: { 
			default: "ds-button-xs", 
			sm: "ds-button-sm", 
			// ... 옵션들 
		}
	}, 
	defaultVariants: { 
			size: "default"
		}, 
	} 
)

• variants: size나 variant(색상) 등을 정의한다. 옵션을 미리 정해두는 곳

🕵️ 코드를 사용하는 곳에서 <Button size="lg">라고 쓰면 ds-button-lg 클래스가 자동으로 붙는다.

---

3. 타입 정의

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean
}

• 이 버튼이 어떤 Props를 받을 수 있는지 정의
• React.ButtonHTMLAttributes를 상속받기 때문에 onClick, type="submit", disabled 같은 표준 버튼 속성을 그대로 다 쓸 수 있다.

---

4. 컴포넌트

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : "button"
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
Button.displayName = "Button"

export { Button, buttonVariants }

• forwardRef: 부모 컴포넌트가 이 버튼의 DOM에 직접 접근(Focus 등)할 수 있게 해준다. 라이브러리 제작 시 필수적인 패턴
• asChild: * false일 때: 기본 <button> 태그로 렌더링된다.
  • true일 때: 새 태그를 만들지 않고 자식(Child) 요소에게 자신의 스타일과 기능을 전달한다.
  • 예: <Button asChild><a href="...">링크</a></Button>라고 쓰면 버튼 모양을 한 <a> 태그가 탄생한다. (HTML 표준 위반인 <button><a></a></button> 구조를 피하기 위함)

---