Tailwind v4 + Vite: 5분 완성 설정 템플릿과 디렉터리 구조

작년에 새 프로젝트에서 Tailwind를 설정하다가 30분 동안 tailwind.config.js의 content 경로만 계속 고친 적이 있습니다. 그때 이런 생각이 들었습니다. 이걸 좀 더 간단하게 만들 수는 없을까?

그리고 올해 Tailwind v4가 정말 그렇게 해냈습니다.

이제 코드 세 줄이면 완전한 Tailwind 프로젝트를 실행할 수 있습니다. PostCSS 설정도, tailwind.config.js도, 심지어 스캔할 파일을 직접 지정할 필요도 없습니다. 이 변화를 처음 봤을 때는 솔직히 좀 믿기지 않았습니다.

이 글은 그 30분의 시행착오를 줄여 드리기 위해 썼습니다. 완성된 템플릿과 함께 반년 동안 사용하며 꽤 편리하다고 느낀 디렉터리 구조도 소개하겠습니다.

1. Tailwind v4 + Vite를 선택하는 이유

1.1 v4는 정말 그렇게 빠를까요?

공식 설명에 따르면 빌드 속도가 10배 향상됐습니다. 직접 테스트해 보니 중소 규모 프로젝트의 빌드 시간이 8초에서 1초 미만으로 줄었습니다. 이러한 향상은 주로 Rust로 작성된 새로운 Oxide 엔진 덕분입니다. 이 정도면 더 설명할 필요도 없겠죠.

하지만 더 반가운 변화는 설정이 간소화됐다는 점입니다. 예전에는 Tailwind 프로젝트를 새로 만들 때 tailwind.config.js, postcss.config.js, Vite 설정, CSS 파일의 @tailwind 지시문까지 서너 개 파일을 수정해야 했습니다. 지금은 어떨까요? 파일 하나만 수정하면 됩니다.

1.2 Vite의 속도는 과장이 아닙니다

Vite 개발 서버는 거의 즉시 시작됩니다. 핫 모듈 교체(HMR)도 매우 빨라서 CSS를 수정하고 페이지를 새로고침해도 지연을 거의 느낄 수 없습니다. 일상적인 개발 경험이 확실히 좋아지며, 솔직히 한 번 써 보면 이전으로 돌아가기 어렵습니다.

1.3 v3 vs v4: 한눈에 보는 비교

먼저 다음 표를 살펴보세요.

차이가 보이시나요? v4의 핵심은 설정을 JS에서 CSS로 옮긴 것입니다. 이것이 무엇을 의미할까요? 스타일을 작성하면서 설정도 바로 수정할 수 있어 두 파일 사이를 오갈 필요가 없습니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

2. 5분 빠른 설정 템플릿

준비되셨나요? 시작해 보겠습니다.

2.1 프로젝트 초기화

터미널을 열고 다음 명령어를 실행합니다.

# TypeScript 템플릿으로 새 Vite 프로젝트 생성
npm create vite@latest my-project -- --template vanilla-ts

# 프로젝트 디렉터리로 이동
cd my-project

# 의존성 설치
npm install

이 단계는 약 30초면 끝납니다.

2.2 Tailwind v4 설치

# Tailwind CSS와 공식 Vite 플러그인 설치
npm install tailwindcss @tailwindcss/vite

이 한 줄이면 됩니다. v4에 이미 내장되어 있으므로 postcss와 autoprefixer는 필요하지 않습니다.

2.3 Vite 설정

vite.config.ts를 열고 다음과 같이 수정합니다.

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  // Tailwind 플러그인만 추가하면 됩니다
  plugins: [tailwindcss()],
})

코드 세 줄입니다. 정말 이게 전부입니다.

2.4 CSS 파일 생성

src/styles/ 아래에 main.css를 생성합니다.

/* src/styles/main.css */

/* Tailwind 불러오기 — 이 한 줄로 모든 기본 스타일이 적용됩니다 */
@import "tailwindcss";

/* 사용자 정의 테마 설정(선택 사항) */
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
}

여기서 @theme 블록은 v4의 새로운 문법입니다. 이 안에서 색상, 글꼴, 간격 등을 CSS 변수 형식으로 정의할 수 있습니다. 예전의 tailwind.config.js보다 훨씬 직관적입니다.

2.5 CSS 불러오기

src/main.ts를 열고 맨 위에 한 줄을 추가합니다.

// src/main.ts
import './styles/main.css'

// 기존 코드...

2.6 테스트하기

index.html이나 페이지 컴포넌트에서 다음 코드를 사용해 보세요.

<div class="bg-primary text-white p-4 rounded-lg">
  Tailwind v4가 실행됩니다!
</div>

그런 다음 다음 명령어를 실행합니다.

npm run dev

브라우저를 열었을 때 파란색 배경의 카드가 보이면 설정에 성공한 것입니다. 직접 시간을 재 봤는데 정말 5분 안에 실행할 수 있었습니다.

3. 권장 디렉터리 구조

프로젝트가 실행된 뒤에는 파일을 다음과 같이 구성하는 것을 권장합니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

3.1 전체 디렉터리 구조

my-project/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── ui/              # 기본 UI 컴포넌트
│   │   │   ├── Button.ts
│   │   │   └── Input.ts
│   │   └── layout/           # 레이아웃 컴포넌트
│   │       ├── Header.ts
│   │       └── Footer.ts
│   ├── styles/
│   │   ├── main.css         # 메인 엔트리(Tailwind 불러오기)
│   │   ├── components.css   # 컴포넌트 관련 스타일
│   │   └── utilities.css    # 사용자 정의 유틸리티 클래스
│   ├── utils/
│   │   └── helpers.ts
│   ├── pages/               # 페이지 파일(멀티 페이지 앱인 경우)
│   ├── assets/              # 정적 리소스
│   │   ├── images/
│   │   └── fonts/
│   ├── main.ts
│   └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

3.2 이렇게 나누는 이유

**components/ui/**에는 버튼, 입력창, 모달 같은 기본 컴포넌트를 둡니다. 재사용성이 높고 구체적인 비즈니스 로직에 의존하지 않는 컴포넌트입니다.

**components/layout/**에는 Header, Footer, Sidebar 같은 레이아웃 컴포넌트를 둡니다. 페이지의 골격을 담당하므로 UI 컴포넌트와 역할이 다릅니다.

**styles/**에는 CSS를 따로 모아 둡니다. Tailwind v4부터는 설정도 CSS에 있기 때문에 스타일을 한곳에서 관리하면 수정하기 편리합니다.

**utils/**에는 유틸리티 함수를 둡니다. 날짜 형식 변환이나 문자열 처리 같은 순수 함수가 여기에 해당합니다.

3.3 CSS 파일 구성 방법

/* src/styles/main.css — 엔트리 파일 */

/* Tailwind 불러오기 */
@import "tailwindcss";

/* 다른 스타일 파일 불러오기 */
@import "./components.css";
@import "./utilities.css";

/* 전역 기본 스타일 */
@layer base {
  body {
    @apply bg-gray-50 text-gray-900;
  }

  /* 링크 기본 스타일 */
  a {
    @apply text-primary hover:underline;
  }
}

@layer base는 가장 기초가 되는 스타일을 정의하는 Tailwind의 레이어 메커니즘입니다. body { ... }를 직접 작성하는 것보다 좋은 점은 Tailwind가 우선순위 문제를 적절히 처리해 준다는 것입니다.

4. v3 마이그레이션 체크리스트

기존 v3 프로젝트를 업그레이드하려면 이 체크리스트를 따라 하면 됩니다. 최근 여러 프로젝트를 업그레이드하면서 겪은 문제도 함께 표시했습니다.

4.1 설정 파일 이전

• tailwind.config.js 삭제(Tailwind 설정만 들어 있는 경우)
• postcss.config.js 삭제(Tailwind에만 사용하는 경우)
• CSS 파일에 @import "tailwindcss" 한 줄 추가
• vite.config.ts를 업데이트해 @tailwindcss/vite 플러그인 사용

4.2 의존성 업데이트

# 기존 의존성 제거
npm uninstall postcss autoprefixer tailwindcss

# 새 의존성 설치
npm install tailwindcss @tailwindcss/vite

• 제거 명령어 실행
• 설치 명령어 실행
• package.json에서 버전 번호 확인

4.3 스타일 조정

• @tailwind base; @tailwind components; @tailwind utilities;를 @import "tailwindcss";로 교체
• tailwind.config.js의 테마 설정을 CSS의 @theme 블록으로 이전
• 사용자 정의 유틸리티 클래스가 정상적으로 작동하는지 확인

테마 설정 이전 예시:

/* v3의 tailwind.config.js */
module.exports = {
  theme: {
    colors: {
      primary: '#3b82f6',
    }
  }
}

/* v4의 main.css */
@theme {
  --color-primary: #3b82f6;
}

4.4 테스트 및 검증

• npm run dev로 개발 환경이 정상인지 확인
• npm run build로 프로덕션 빌드가 성공하는지 확인
• 페이지를 열어 스타일이 누락되지 않았는지 확인
• CSS 파일을 수정해 핫 업데이트가 작동하는지 확인

5. 자주 발생하는 문제와 해결 방법

업그레이드와 설정 과정에서 가장 자주 겪은 문제는 다음과 같습니다.

5.1 스타일이 적용되지 않음

class="bg-primary"를 작성했는데 페이지가 온통 흰색입니다. 무엇이 문제일까요?

확인 순서:

1. 브라우저 개발자 도구를 열어 CSS 파일이 정상적으로 로드되었는지 확인합니다.
2. main.ts에서 CSS 파일을 실제로 불러왔는지 확인합니다.
3. vite.config.ts의 플러그인이 올바르게 설정되었는지 확인합니다.

한 번은 main.ts에 import './styles/main.css'를 추가하는 것을 잊어서 이런 문제가 생겼습니다. 단순한 실수지만 놓치기 쉽습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

5.2 핫 업데이트가 작동하지 않음

CSS를 수정했는데 페이지가 전혀 바뀌지 않습니다.

확인 순서:

1. Vite 버전이 >= 5.0인지 확인합니다(이전 버전에는 호환성 문제가 있습니다).
2. 개발 서버를 다시 시작해 봅니다.
3. 브라우저 캐시를 삭제하거나 시크릿 창을 엽니다.

그래도 해결되지 않으면 콘솔에 오류가 있는지 확인하세요. 다른 플러그인과의 충돌이 원인일 때도 있습니다.

5.3 빌드 후 CSS 파일이 너무 큼

프로덕션 빌드 결과 CSS 파일이 수백 KB에 달합니다.

확인 순서:

1. v4의 최신 버전을 사용하고 있는지 확인합니다. 이전 버전은 tree-shaking이 충분히 깔끔하지 않습니다.
2. 전체 아이콘 라이브러리나 다른 대형 의존성을 불러오지 않았는지 확인합니다.
3. @layer로 스타일을 계층화하면 Tailwind가 우선순위와 중복 제거를 더 잘 처리할 수 있습니다.

솔직히 대부분의 경우 v4의 출력은 이미 매우 간결합니다. 그래도 너무 크다면 CSS에 직접 작성한 내용이 지나치게 많을 가능성이 큽니다.

마무리

지금까지 설명한 내용의 핵심은 다음 네 가지입니다.

1. 설치: npm install tailwindcss @tailwindcss/vite
2. Vite 설정: tailwindcss() 플러그인 하나 추가
3. CSS 작성: @import "tailwindcss" + @theme로 테마 설정
4. 실행: npm run dev

v4와 v3의 가장 큰 차이는 설정을 JS에서 CSS로 옮겼다는 점입니다. 처음에는 조금 낯설 수 있지만 한동안 사용해 보니 훨씬 직관적이었습니다. 스타일을 수정하면서 설정도 함께 바꿀 수 있어 파일 사이를 오갈 필요가 없습니다.

v3에서 이전한다면 tailwind.config.js의 테마 설정을 CSS의 @theme 문법으로 변환하는 것을 잊지 마세요. 시간이 조금 들기는 하지만 더 빠른 빌드 속도와 더 간결한 프로젝트 구조를 얻을 수 있으니 충분히 가치 있는 작업입니다.