Tailwind CSS 버전 정리

안녕하세요 웹 YB 정희연입니다!

최근 Tailwind를 처음 접해보면서 여러 오류를 겪게 되었는데요! 알고 보니 버전별로 지원하는 설정 방식과 기능이 다르더라구요

여러 자료를 찾아보며 적용하다보니 버전마다의 설정이 섞이게 되어 오류가 발생했었습니다..💦

이 경험을 계기로 Tailwind의 버전을 정리하고자 합니다.

---

1. 버전별 주요 차이점 요약

💭 Tailwind CSS v1.x

• 기본적인 기능 제공 (색상, 여백, 반응형 등)
• 사용자 커스터마이징은 tailwind.config.js에 제한적으로
• 대부분의 스타일을 컴포넌트 파일에서 직접 사용

디렉토리 구조 예시 (v1.x) 

project/
  └─ src/
      └─ components/
      └─ App.css (tailwind import 포함)
  └─ tailwind.config.js
  └─ postcss.config.js

 

💭 Tailwind CSS v2.x

 

• Dark mode, JIT 모드, 새로운 색상 시스템 등 추가됨
• 커스터마이징 강력해짐
• @layer 문법 적극 사용되기 시작

디렉토리 구조 예시 (v2.x) 

project/
  └─ src/
      └─ styles/
          └─ index.css (@tailwind base/components/utilities 사용)
  └─ tailwind.config.js
  └─ postcss.config.js

 

 

💭 Tailwind CSS v3.x

 

• JIT(Just-in-Time) 모드가 기본값으로 적용됨 → purge 대신 content 사용
• 설정 파일에서 content: ['./src/**/*.{js,ts,jsx,tsx}']처럼 경로 설정 필요
•  @layer를 활용한 사용자 정의 클래스 정의가 일반화됨
• 플러그인 사용이 많아짐 (tailwindcss/forms, typography 등)

디렉토리 구조 예시 (v3.x) 

project/
  └─ src/
      └─ components/
      └─ pages/
      └─ styles/
          ├─ global.css  → @tailwind base/components/utilities
          ├─ theme.css   → 커스텀 변수들
  └─ tailwind.config.js
  └─ postcss.config.js
  └─ prettier.config.js  (prettier-plugin-tailwindcss와 함께 사용)

 

 

💭 Tailwind CSS v4.0 주요 변화(가장 최근)

1).  PostCSS 의존성 제거

 

• postcss.config.js 없이도 Tailwind를 사용할 수 있게 됨
• 즉, 설정이 더 간결해지고 설치할 의존성도 줄어듦
• 하지만 여전히 PostCSS를 사용하고 싶다면 기존 방식도 사용 가능
• Tailwind v4부터는 PostCSS 플러그인을 직접 사용할 수 없고, "@tailwindcss/postcss"라는 별도 패키지를 설치 필요

yarn add -D @tailwindcss/postcss

2). 콘피그 파일 개선

• tailwind.config.js를 매우 간단하게 만들 수 있음

예시

// tailwind.config.js
export default {
  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
}

• ESM(.js 확장자 + "type": "module") 환경이 기본이므로, module.exports 대신 export default 사용

3). @tailwind base, @tailwind components 제거

<기존>

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

 

<v4>

@import "tailwindcss/preflight";
@import "tailwindcss/utilities";

 

---

2. 폴더 구조 변화

-> 본질적으로 큰 변화는 없지만 설정 파일과 사용 방식이 단순해져서 구조가 더 심플해짐

 

Tailwind v4 기준 추천 폴더 구조

project/
├─ src/
│  ├─ components/
│  ├─ pages/
│  └─ App.jsx
├─ tailwind.config.js
├─ index.css (선택사항, 필요 시 @tailwind 지시어 사용)
└─ package.json

 

 

index.css가 아예 없어도 되고, 필요하면 넣어도 됨
Tailwind는 v4부터 "Zero-runtime CSS"라는 철학을 추구하기 때문에

빌드 시 필요한 클래스만 생성하고, 최소한의 설정으로 시작하는 걸 지향!

 

---

3. 버전별 차이 요약 

항목	v1.x	v2.x	v3.x	v4.x (최신)
@apply 지원	제한적	본격 지원	적극 권장	동일
설정 방식 (purge vs content)	없음 또는 기본	purge 사용	content로 변경됨	content, PostCSS 생략 가능
PostCSS 필요 여부	필수	필수	필수	선택사항 (의존성 제거됨)
JIT 모드	없음	실험적	기본 적용	기본 적용
tailwind.config.js 형식	module.exports만 가능	module.exports만 가능	module.exports or ESM 가능	ESM(export default) 권장
@tailwind 디렉티브 필요 여부	필수	필수	필수	생략 가능 (index.css 없이도 가능)

---

4. 겪은 오류와 해결법

오류 1: Cannot apply unknown utility class: font-bold

Error: Cannot apply unknown utility class: font-bold

💡 원인

Tailwind v4는 @apply에서 일부 유틸리티 클래스(예: font-bold, font-semibold) 사용 제한

✅ 해결

/* 오류 발생 */
@apply font-bold;

/* 수정 */
font-weight: 700;

 

오류 2: postcss plugin 관련 에러

It looks like you're trying to use tailwindcss directly as a PostCSS plugin...

💡 원인

 

Tailwind v4부터는 PostCSS 플러그인을 분리했기 때문에 기존 설정이 작동하지 않음

✅ 해결

yarn add -D @tailwindcss/postcss

//postcss.config.js

import tailwindcss from '@tailwindcss/postcss';
import autoprefixer from 'autoprefixer';

export default {
  plugins: [tailwindcss(), autoprefixer()],
};

 

오류 3: 클래스 적용 X

💡 원인

Tailwind는 content 경로에 나타나지 않은 클래스는 자동으로 제거(JIT purge)

✅ 해결 1

safelist에 강제로 포함

safelist: ['bg-green-200', 'font-bold']

✅ 해결 2

커스텀 클래스로 정의

.bg-Mainblue { background-color: #0073F9; }

 

정리

항목	상태
@apply 오류 대응	직접 CSS로 대체
색상 클래스 정리	.text-*, .bg-* 방식
PostCSS 설정 변경	@tailwindcss/postcss 사용

---

📚 참고자료

https://tailwindcss.com/blog/tailwindcss-v4

Tailwind CSS v4.0

https://tailwindcss.com/docs/installation/using-vite

Installing with Vite - Installation

https://tailwindcss.com/docs/upgrade-guide

Upgrade guide - Getting started