🔗 Tailwind 13장: Next.js + Tailwind 완벽 연동

2026년 3월 5일 수정됨

📋 개요

Next.js App Router 환경에서 Tailwind 를 올바르게 통합하는 법 — 설치부터 next/font, Server Components, shadcn/ui 까지

📋 목차

📌 이 문서를 읽기 전에
🤔 왜 알아야 하는가
⚙️ 설치와 초기 설정
🖋️ next/font 와 Tailwind 통합
🖥️ Server Components 에서 Tailwind
🌙 next-themes 다크 모드 통합
🧩 shadcn/ui: Tailwind 기반 컴포넌트 라이브러리
💻 실전: 영수네 커뮤니티 Next.js 프로젝트 구조
🚨 Next.js + Tailwind 흔한 함정
🏁 이번에 배운 내용 총정리
📝 마무리 퀴즈
[🐣 영철이의 퇴근 일기](#-영철이의-퇴근 일기)
🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분

🎯 이 문서를 다 읽으면 할 수 있는 것

create-next-app 으로 Tailwind 포함 프로젝트를 올바르게 세팅할 수 있다
next/font 로 한국어 폰트를 최적화해서 Tailwind 와 통합할 수 있다
Server Components 와 Client Components 에서 Tailwind 를 올바르게 사용할 수 있다
shadcn/ui 를 프로젝트에 추가하고 커스터마이징할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

🐣 영철 (신입): "리드 님! Next.js 새 프로젝트 시작하는데, Tailwind 설정을 어떻게 해야 해요? 공식 문서 보니까 버전마다 설정이 달라서 헷갈려요."
🦁 영호 (리드): "영철 님, create-next-app 으로 시작하면 Tailwind 설정까지 자동으로 돼요. 근데 한국어 폰트랑 다크 모드, shadcn/ui 추가하는 부분이 좀 까다롭거든요. 한 번에 제대로 잡아봐요."
👔 영수 (PM): "설정 얼마나 걸려요? 빨리 기능 만들고 싶은데."
🦁 영호: "오늘 중으로 완벽하게 세팅해드릴게요. 초반에 제대로 잡으면 나중에 훨씬 편해요."

🤔 왜 알아야 하는가

Tailwind 를 Next.js 와 통합할 때는 몇 가지 고려할 점이 있어:

폰트 최적화: next/font 와 CSS 변수를 통해 Tailwind 폰트 유틸리티와 연결
다크 모드: Server/Client Component 경계에서 안전하게 처리
CSS 파일 위치: App Router 에서는 app/globals.css 에 임포트
shadcn/ui: Tailwind 기반 컴포넌트 라이브러리와 충돌 없이 설정

이것들을 처음부터 올바르게 잡지 않으면 나중에 대규모 리팩토링이 필요해.

⚙️ 설치와 초기 설정

새 프로젝트: create-next-app (권장)

# Tailwind 포함 자동 설정
npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

이 명령으로 생성된 프로젝트에는 이미 포함돼 있어:

tailwindcss (v4 또는 v3, Next.js 버전에 따라)
postcss, autoprefixer
tailwind.config.ts 또는 globals.css 에 @import "tailwindcss"

기존 프로젝트에 Tailwind 추가

# Tailwind v4 (최신)
npm install tailwindcss @tailwindcss/postcss postcss
 
# postcss.config.mjs
# { plugins: { '@tailwindcss/postcss': {} } }

/* app/globals.css */
@import "tailwindcss";

생성된 파일 구조

my-app/
├── app/
│   ├── globals.css     ← Tailwind 임포트 위치
│   ├── layout.tsx      ← globals.css 임포트
│   └── page.tsx
├── tailwind.config.ts  ← Tailwind v3 설정 (v4 에서는 불필요)
├── postcss.config.mjs  ← PostCSS 설정
└── package.json

🖋️ next/font 와 Tailwind 통합

한국어 Noto Sans KR 적용

// app/layout.tsx
import { Noto_Sans_KR, Inter } from 'next/font/google';
import './globals.css';
 
// 영어 폰트
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',   // CSS 변수 이름
  display: 'swap',
});
 
// 한국어 폰트 (필요한 굵기만 로드해서 최적화)
const notoSansKr = Noto_Sans_KR({
  subsets: ['latin'],
  weight: ['400', '500', '700'],  // 필요한 굵기만
  variable: '--font-noto-sans-kr',
  display: 'swap',
});
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    // className 에 두 폰트 변수 모두 추가
    <html lang="ko" className={`${inter.variable} ${notoSansKr.variable}`}>
      <body className="font-sans antialiased">
        {children}
      </body>
    </html>
  );
}

/* app/globals.css */
@import "tailwindcss";
 
@theme {
  /* next/font 가 생성한 CSS 변수를 Tailwind 폰트로 등록 */
  --font-sans: var(--font-noto-sans-kr), var(--font-inter), system-ui, sans-serif;
  --font-mono: ui-monospace, 'JetBrains Mono', monospace;
}

이제 font-sans 클래스를 쓰면 Noto Sans KR → Inter → system-ui 폴백 순으로 적용돼.

로컬 폰트 (Pretendard) 적용

// app/layout.tsx
import localFont from 'next/font/local';
 
const pretendard = localFont({
  src: [
    { path: '../public/fonts/Pretendard-Regular.woff2',  weight: '400' },
    { path: '../public/fonts/Pretendard-Medium.woff2',   weight: '500' },
    { path: '../public/fonts/Pretendard-SemiBold.woff2', weight: '600' },
    { path: '../public/fonts/Pretendard-Bold.woff2',     weight: '700' },
  ],
  variable: '--font-pretendard',
  display: 'swap',
});

🖥️ Server Components 에서 Tailwind

Server vs Client Component 에서의 차이

// ✅ Server Component — Tailwind 클래스 그냥 사용 (가장 일반적)
// app/components/StudyCard.tsx (서버 컴포넌트 기본)
export function StudyCard({ title, description }: Props) {
  return (
    <div className="rounded-xl border border-gray-200 bg-white p-5 shadow-md">
      <h3 className="text-lg font-bold text-gray-900">{title}</h3>
      <p className="text-sm text-gray-500">{description}</p>
    </div>
  );
}

// ✅ Client Component — 인터랙션이 필요한 경우에만
// 'use client' 가 붙어도 Tailwind 클래스는 동일하게 사용
'use client';
 
import { useState } from 'react';
 
export function ExpandableCard({ title, content }: Props) {
  const [expanded, setExpanded] = useState(false);
 
  return (
    <div className="rounded-xl border border-gray-200 bg-white shadow-md">
      <button
        onClick={() => setExpanded(!expanded)}
        className="flex w-full items-center justify-between p-5 text-left"
      >
        <h3 className="font-bold text-gray-900">{title}</h3>
        <span className={`transition-transform ${expanded ? 'rotate-180' : ''}`}>▼</span>
      </button>
      {expanded && (
        <div className="border-t border-gray-100 p-5 text-sm text-gray-600">
          {content}
        </div>
      )}
    </div>
  );
}

💡 Server Component 에서 Tailwind 를 쓰면 서버에서 HTML 렌더링 시 이미 클래스가 포함돼. 별도 JS 번들 없이 스타일이 적용되어 FCP(First Contentful Paint) 가 빨라져.

Conditional Classes in Server Components

// Server Component 에서도 cn() 패턴 사용 가능
import { cn } from '@/lib/utils';
 
// async Server Component
async function StudyStatus({ studyId }: { studyId: string }) {
  const study = await getStudy(studyId);  // 서버에서 직접 DB 조회
 
  return (
    <span className={cn(
      'rounded-full px-3 py-1 text-xs font-semibold',
      study.status === 'recruiting' && 'bg-green-100 text-green-700',
      study.status === 'ongoing'    && 'bg-blue-100 text-blue-700',
      study.status === 'completed'  && 'bg-gray-100 text-gray-500',
    )}>
      {study.statusLabel}
    </span>
  );
}

🌙 next-themes 다크 모드 통합

(07장에서 다뤘지만 Next.js 컨텍스트에서 다시 정리)

npm install next-themes

// app/providers.tsx
'use client';
 
import { ThemeProvider } from 'next-themes';
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider
      attribute="class"       // <html class="dark"> 방식 사용
      defaultTheme="system"   // 시스템 설정 기본값
      enableSystem            // 시스템 설정 감지
      disableTransitionOnChange // 테마 전환 시 transition 일시 비활성 (깜빡임 방지)
    >
      {children}
    </ThemeProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko" suppressHydrationWarning>  {/* 필수! */}
      <body className="bg-gray-50 text-gray-900 dark:bg-gray-900 dark:text-white antialiased">
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

🧩 shadcn/ui: Tailwind 기반 컴포넌트 라이브러리

shadcn/ui 는 Tailwind + Radix UI 기반의 컴포넌트 라이브러리로, 코드를 복사해서 프로젝트에 직접 소유하는 독특한 방식이야.

설치

npx shadcn@latest init

설치 과정에서:

TypeScript 사용 여부
스타일 (Default or New York)
기본 색상 (브랜드 컬러)
CSS 변수 사용 여부
components.json 생성

컴포넌트 추가

# 원하는 컴포넌트만 선택적으로 추가
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add input
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast

추가된 파일 위치: components/ui/button.tsx, components/ui/card.tsx 등

shadcn/ui 와 커스텀 Tailwind 테마 연동

/* globals.css */
@import "tailwindcss";
 
@theme {
  /* shadcn/ui 가 사용하는 CSS 변수와 매핑 */
  --color-background: hsl(0 0% 100%);
  --color-foreground: hsl(222.2 84% 4.9%);
  --color-primary: hsl(222.2 47.4% 11.2%);
  --color-primary-foreground: hsl(210 40% 98%);
  --color-secondary: hsl(210 40% 96.1%);
  --color-secondary-foreground: hsl(222.2 47.4% 11.2%);
  --color-muted: hsl(210 40% 96.1%);
  --color-muted-foreground: hsl(215.4 16.3% 46.9%);
  --color-accent: hsl(210 40% 96.1%);
  --color-accent-foreground: hsl(222.2 47.4% 11.2%);
  --color-border: hsl(214.3 31.8% 91.4%);
  --color-ring: hsl(222.2 84% 4.9%);
 
  /* 다크 모드 */
  /* .dark 클래스 내에서 오버라이드 */
}

shadcn/ui 컴포넌트 커스터마이징

shadcn/ui 의 가장 큰 장점: 컴포넌트 코드가 내 프로젝트에 있어서 자유롭게 수정 가능!

// components/ui/button.tsx (shadcn/ui 가 생성한 파일 — 직접 수정 가능)
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
 
const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default:     'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline:     'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
        secondary:   'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost:       'hover:bg-accent hover:text-accent-foreground',
        link:        'text-primary underline-offset-4 hover:underline',
        // 🎨 커스텀 variant 추가 — 영수네 브랜드 버튼
        brand:       'bg-brand-600 text-white hover:bg-brand-700 focus-visible:ring-brand-500',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm:      'h-9 rounded-md px-3',
        lg:      'h-11 rounded-md px-8',
        icon:    'h-10 w-10',
      },
    },
    defaultVariants: { variant: 'default', size: 'default' },
  }
);
 
// 사용 예
<Button variant="brand">영수네 브랜드 버튼</Button>

💻 실전: 영수네 커뮤니티 Next.js 프로젝트 구조

완성된 layout.tsx

// app/layout.tsx
import type { Metadata } from 'next';
import { Noto_Sans_KR, Inter } from 'next/font/google';
import { Providers } from './providers';
import './globals.css';
 
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
  display: 'swap',
});
 
const notoSansKr = Noto_Sans_KR({
  subsets: ['latin'],
  weight: ['400', '500', '700'],
  variable: '--font-noto-sans-kr',
  display: 'swap',
});
 
export const metadata: Metadata = {
  title: '영수네 커뮤니티',
  description: '개발자 스터디 매칭 플랫폼',
};
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      lang="ko"
      className={`${inter.variable} ${notoSansKr.variable}`}
      suppressHydrationWarning  // next-themes 다크 모드용
    >
      <body className={`
        min-h-screen
        bg-gray-50 text-gray-900
        dark:bg-gray-900 dark:text-white
        antialiased font-sans
      `}>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

완성된 globals.css

/* app/globals.css */
@import "tailwindcss";
 
/* ===== 디자인 토큰 ===== */
@theme {
  /* 폰트 (next/font CSS 변수 참조) */
  --font-sans: var(--font-noto-sans-kr), var(--font-inter), system-ui, sans-serif;
 
  /* 브랜드 색상 */
  --color-brand-500: #8b5cf6;
  --color-brand-600: #7c3aed;
  --color-brand-700: #6d28d9;
 
  /* 커스텀 Breakpoint */
  --breakpoint-xs: 30rem;
}
 
/* ===== Base 스타일 ===== */
@layer base {
  html { scroll-behavior: smooth; }
  body { word-break: keep-all; }
 
  /* 전역 포커스 스타일 */
  *:focus-visible {
    outline: 2px solid theme('colors.brand.600');
    outline-offset: 2px;
  }
}

🚨 Next.js + Tailwind 흔한 함정

함정 1: globals.css 임포트 위치

// ❌ 개별 페이지에서 임포트 — Next.js 는 layout 에서만 허용
// app/studies/page.tsx
import '../globals.css';  // 경고 발생!
 
// ✅ 루트 layout 에서 한 번만 임포트
// app/layout.tsx
import './globals.css';  // 여기서만!

함정 2: Server Component 에서 useState 와 Tailwind

// ❌ Server Component 에서 동적 클래스를 useState 로 관리 불가
export default function StudyCard() {
  const [isHovered, setIsHovered] = useState(false);  // Server Component 에서 에러!
  return <div className={isHovered ? 'bg-blue-50' : 'bg-white'}>...</div>;
}
 
// ✅ hover 는 CSS 로 (Tailwind variant 사용) — JS 불필요
export default function StudyCard() {
  return <div className="bg-white hover:bg-blue-50 transition-colors">...</div>;
}
 
// ✅ 진짜 상태가 필요하면 'use client' 추가
'use client';
export default function StudyCard() {
  const [isExpanded, setIsExpanded] = useState(false);
  // ...
}

함정 3: 다크 모드 Hydration 불일치

// ❌ 서버에서 다크 모드 상태를 알 수 없어서 깜빡임 발생
<html className={isDark ? 'dark' : ''}>
 
// ✅ next-themes + suppressHydrationWarning 으로 해결
<html suppressHydrationWarning>  {/* ThemeProvider 가 알아서 처리 */}

함정 4: Tailwind v3 vs v4 설정 차이

v3: tailwind.config.ts 필요 + postcss.config.js
v4: globals.css 에 @import "tailwindcss" 만 있으면 됨 (config 파일 불필요)

/* v4 설정 확인: globals.css 에 이게 있으면 v4 */
@import "tailwindcss";
 
/* v3 확인: tailwind.config.ts 에 이게 있으면 v3 */
/* content: ['./src/**/*.{ts,tsx}', './app/**/*.{ts,tsx}'] */

🏁 이번에 배운 내용 총정리

항목	방법	주의사항
새 프로젝트	`create-next-app --tailwind`	자동 설정됨
next/font 통합	CSS 변수 → `@theme` 등록	display: swap 필수
globals.css 위치	`app/layout.tsx` 에서 임포트	다른 곳 X
다크 모드	next-themes + suppressHydrationWarning	mounted 체크
shadcn/ui	`npx shadcn@latest add`	코드 직접 소유
Server Component	hover 는 CSS variant, 상태는 'use client'	JS 최소화

📝 마무리 퀴즈

Q1. Next.js App Router 에서 globals.css 를 임포트해야 하는 올바른 위치는?

✅ 정답: 루트 app/layout.tsx 에서 한 번만 임포트한다.

💡 상세 해설:

Next.js App Router 에서 CSS 파일은 루트 레이아웃에서 임포트해야 전체 앱에 적용돼. 다른 파일에서 임포트하면 경고 또는 오류가 발생할 수 있어.
import './globals.css' 는 app/layout.tsx 맨 위에 한 번만 위치해야 해.
페이지별 CSS Modules (.module.css)는 각 컴포넌트에서 임포트 가능하지만, 전역 CSS 는 루트에서만.
📌 핵심 기억법: "전역 CSS = 루트 layout 에서 한 번만."

Q2. next/font 로 로드한 폰트를 Tailwind font-sans 클래스와 연결하는 방법은?

✅ 정답: next/font 에서 variable 옵션으로 CSS 변수 이름을 지정하고, @theme 에서 그 변수를 --font-sans 에 등록한다.

💡 상세 해설:

next/font 설정: variable: '--font-noto-sans-kr'
HTML 에 변수 주입: <html className={notoSansKr.variable}>
@theme 등록: --font-sans: var(--font-noto-sans-kr), sans-serif;
사용: <body className="font-sans">

이 흐름이 next/font 와 Tailwind 를 연결하는 공식 패턴이야.

📌 핵심 기억법: "next/font variable → html 클래스 → @theme → font-sans 클래스."

Q3. shadcn/ui 가 기존 라이브러리(@mui/material, @chakra-ui 등)와 다른 핵심 차이점은?

✅ 정답: shadcn/ui 는 설치 후 컴포넌트 코드를 프로젝트 안에 직접 복사해서 완전한 소유권을 가진다. 라이브러리 업데이트의 영향을 받지 않고, 자유롭게 수정할 수 있다.

💡 상세 해설:

MUI, Chakra UI 는 node_modules 에 있어서 코드를 직접 수정할 수 없고, 업데이트 시 변경사항을 그대로 받아야 해.
shadcn/ui 는 npx shadcn@latest add button 을 하면 components/ui/button.tsx 파일이 내 프로젝트에 생성돼. 이 파일은 내 것이라 마음대로 수정 가능.
단점: 새 버전의 버그 수정이나 기능 추가를 자동으로 받을 수 없어. 수동으로 다시 실행하거나 직접 수정해야 해.
📌 핵심 기억법: "shadcn = 레시피 제공. 요리는 네가 해. MUI = 완성 요리 배달."

🐣 영철이의 퇴근 일기

오늘로 Tailwind 시리즈가 진짜 끝났다. 처음 1장에서 "클래스가 너무 많아서 불편해요" 라고 투덜거리던 내가, 이제는 cva, cn(), @theme, next-themes, shadcn/ui 까지 자연스럽게 쓸 수 있게 됐다.

Next.js 연동 파트가 사실 제일 헷갈렸는데, 영호 님이 globals.css 임포트 위치, next/font CSS 변수 연결, suppressHydrationWarning 이유까지 하나씩 설명해주니까 퍼즐이 맞춰지는 느낌이었다.

💡 오늘의 교훈: "Next.js + Tailwind 의 핵심은 '서버에서 최대한, 클라이언트는 최소한'. hover/focus 는 CSS 로, 실제 상태 변화만 use client 로."

이제 영수네 커뮤니티 프로젝트에서 배운 걸 전부 적용해볼 수 있겠다. 영호 님한테 오늘 배운 내용 바탕으로 컴포넌트 라이브러리 PR 올리면, 드디어 "잘 됐네요" 라는 말 들을 수 있지 않을까? 두근두근하면서 기대도 된다. 내일도 파이팅! 🚀

🔗 Tailwind 13장: Next.js + Tailwind 완벽 연동

📋 목차

📌 이 문서를 읽기 전에

🤔 왜 알아야 하는가

⚙️ 설치와 초기 설정

새 프로젝트: create-next-app (권장)

기존 프로젝트에 Tailwind 추가

생성된 파일 구조

🖋️ next/font 와 Tailwind 통합

한국어 Noto Sans KR 적용

로컬 폰트 (Pretendard) 적용

🖥️ Server Components 에서 Tailwind

Server vs Client Component 에서의 차이

Conditional Classes in Server Components

🌙 next-themes 다크 모드 통합

🧩 shadcn/ui: Tailwind 기반 컴포넌트 라이브러리

설치

컴포넌트 추가

shadcn/ui 와 커스텀 Tailwind 테마 연동

shadcn/ui 컴포넌트 커스터마이징

💻 실전: 영수네 커뮤니티 Next.js 프로젝트 구조

추천 폴더 구조

완성된 layout.tsx

완성된 globals.css

🚨 Next.js + Tailwind 흔한 함정

함정 1: globals.css 임포트 위치

함정 2: Server Component 에서 useState 와 Tailwind

함정 3: 다크 모드 Hydration 불일치

함정 4: Tailwind v3 vs v4 설정 차이

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

🐣 영철이의 퇴근 일기

🔗 더 알아보기