Tailwind CSS 설치 시 v3는 잘 되는데, v4는 왜 오류가 날까?

목차

• Tailwind v3 설치가 잘 되는 이유
• Tailwind v4에서 발생하는 문제
• Tailwind v3를 사용하는 장점
• CRA 기반 호환 버전 요약
• 결론 및 추천

---

Tailwind v3 설치가 잘 되는 이유

최근 React(CRA 기반) 프로젝트에서 Tailwind CSS를 설치하면서 버전 3.4.17을 사용했더니 별다른 설정 없이도 곧바로 작동했습니다.

npm install -D tailwindcss@3.4.17 postcss autoprefixer

 

설치 후 아래 명령어도 문제없이 실행되었습니다.

npx tailwindcss init -p

 

왜 이렇게 간단하게 작동했을까요? 그 이유는 Tailwind CSS v3와 CRA(create-react-app)의 높은 호환성 덕분입니다.

특히 다음과 같은 조합에서는 특별한 설정 없이도 잘 작동합니다:

• Windows 운영체제
• PowerShell 터미널
• CRA 기반 프로젝트 구조

---

Tailwind v4에서 발생하는 문제

Tailwind CSS v4부터는 CLI 실행 방식과 내부 구조가 바뀌면서, 일부 환경에서는 문제가 생기기 시작했습니다.

특히 아래 조건을 동시에 만족할 경우, 오류가 발생할 가능성이 높습니다:

• create-react-app으로 생성된 프로젝트
• Windows + PowerShell 환경
• Tailwind CLI를 글로벌이 아닌 로컬로 설치한 경우

문제의 원인은 보통 다음 중 하나입니다:

• node_modules/.bin에 Tailwind CLI가 정상 설치되지 않음
• PowerShell에서 실행 권한 문제로 CLI 실행 자체가 막힘
• Tailwind 4의 기본 설정 파일이 CRA와 충돌하거나 정상 인식되지 않음

이런 문제 때문에, tailwind.config.js가 제대로 작동하지 않거나, 빌드 시 에러가 나며 화면에 스타일이 적용되지 않는 경우가 많습니다.

---

Tailwind v3를 사용하는 장점

TailwindCSS v3는 2023년 중반까지 React + CRA 환경의 사실상 표준 조합으로 사용되어 왔으며, 지금도 매우 안정적입니다.

특히 다음과 같은 점에서 유리합니다:

• CRA 프로젝트와 공식적으로 검증된 호환성
• npx tailwindcss init -p 명령이 바로 작동
• v4에 비해 설정 파일 충돌이나 CLI 오류가 거의 없음
• 문서화와 커뮤니티 지원이 풍부

실제로 많은 개발자들이 CRA에서는 Tailwind v3, Vite나 Next.js에서는 v4를 선택하는 흐름을 따릅니다.

---

CRA 기반 호환 버전 요약

항목	권장 버전	비고
React	18.x	CRA 최신 버전 기준
Tailwind CSS	3.4.17	v4는 CRA와 일부 충돌
Node.js	16 ~ 18	버전 호환성 중요

---

결론 및 추천

현재 React 프로젝트에서 Tailwind CSS를 적용하려는 경우, 아래 조건을 체크해보세요:

• create-react-app을 사용하고 있다면 Tailwind v3.4.17을 사용하는 것이 좋습니다.
• v4는 아직 CRA와 완벽하게 호환되지 않으며, CLI 실행 문제 등 예상치 못한 이슈가 생길 수 있습니다.
• Next.js, Vite 기반 프로젝트에서는 Tailwind v4를 자유롭게 사용해도 됩니다.

따라서 지금과 같은 상황이라면, Tailwind v3를 쓰는 것이 안정적이고, 실제로 많은 실무 프로젝트에서도 여전히 v3를 사용하고 있습니다.

 

이후 프로젝트가 Vite 기반으로 전환되거나, Tailwind 공식 문서에서 CRA 호환성에 대한 개선이 이루어지면 그때 Tailwind v4를 시도해보는 것도 좋습니다.

 

정리하면:

1. React(CRA) 기반: Tailwind v3 추천
2. Vite 기반: Tailwind v4도 OK

지금처럼 npm install -D tailwindcss@3.4.17 명령으로 설치되었다면, 매우 적절한 선택을 하신 겁니다!