Vite 환경에서 Tailwind CSS v4 업데이트 후 발생하는 PostCSS 에러 해결 방법
Problem
프론트엔드 프로젝트에서 의존성을 최신화하기 위해 node_modules를 지우고 npm install을 다시 실행한 후 빌드(npm run build)를 시도할 때 에러가 발생하는 경우가 있습니다. 이때 터미널에 [postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin 또는 Missing "./components" specifier in "tailwindcss" package와 같은 에러 메시지가 출력됩니다. 이는 프로젝트가 정상적으로 작동하다가 패키지를 재설치한 직후에 갑자기 발생하는 매우 당혹스러운 문제입니다.
Background
이 문제는 최근 출시된 Tailwind CSS v4의 대대적인 아키텍처 변경 때문에 발생합니다. npm install tailwindcss를 실행하면 기본적으로 최신 버전인 v4가 설치되는데, v4는 기존 v3와 설치 및 설정 방식이 완전히 다릅니다.
가장 큰 변화는 Tailwind CSS가 더 이상 PostCSS 플러그인을 기본으로 내장하지 않는다는 것입니다. v4에서는 PostCSS 플러그인이 @tailwindcss/postcss라는 별도의 패키지로 분리되었습니다. 또한, Vite 환경을 위한 전용 플러그인(@tailwindcss/vite)이 새롭게 도입되었으며, 기존의 자바스크립트 기반 설정 파일(tailwind.config.js) 대신 CSS 파일 내에서 직접 설정하는 ‘CSS-first’ 방식을 채택했습니다. 따라서 기존 v3 방식의 PostCSS 설정이 남아있는 상태에서 v4 패키지가 설치되면 호환성 충돌로 인해 에러가 발생하게 됩니다.
Solution
이 문제를 해결하는 방법은 프로젝트를 Tailwind CSS v4로 완전히 마이그레이션하거나, 기존 v3 버전을 명시적으로 유지하는 것입니다. 상황에 맞게 아래 세 가지 방법 중 하나를 선택하세요.
방법 1: Vite 전용 플러그인으로 전환하기 (v4 권장 방식)
Vite를 사용 중이라면 PostCSS를 거치지 않고 Tailwind CSS의 Vite 전용 플러그인을 사용하는 것이 가장 빠르고 권장되는 방법입니다.
- 기존 PostCSS 관련 패키지를 제거하고 새로운 Vite 플러그인을 설치합니다.
# 기존 postcss, autoprefixer 제거
npm uninstall postcss autoprefixer
# tailwindcss v4 및 vite 플러그인 설치
npm install -D tailwindcss @tailwindcss/vite
-
프로젝트 루트에 있는
postcss.config.js(또는.cjs) 파일을 삭제합니다. -
vite.config.ts(또는.js) 파일을 수정하여 Tailwind 플러그인을 추가합니다.
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite' // 플러그인 임포트
export default defineConfig({
plugins: [
react(),
tailwindcss(), // 플러그인 배열에 추가
],
})
- 메인 CSS 파일(예:
index.css)의 내용을 모두 지우고 아래 한 줄로 교체합니다. v4에서는 기존의@tailwind디렉티브를 사용하지 않습니다.
/* index.css */
@import "tailwindcss";
방법 2: PostCSS 환경 유지하기 (v4)
만약 다른 PostCSS 플러그인을 함께 사용해야 해서 PostCSS 환경을 유지해야 한다면, 분리된 PostCSS 패키지를 설치해야 합니다.
- 패키지 재설치 (v4에서는
autoprefixer가 더 이상 필요하지 않습니다.)
# autoprefixer 제거
npm uninstall autoprefixer
# 분리된 postcss 플러그인 설치
npm install -D tailwindcss @tailwindcss/postcss postcss
postcss.config.js파일을 업데이트합니다.
// postcss.config.js
export default {
plugins: {
'@tailwindcss/postcss': {}, // 기존 'tailwindcss'를 변경
},
}
방법 3: Tailwind CSS v3 버전으로 롤백하기
당장 v4로의 마이그레이션이 부담스럽다면, 패키지 버전을 v3로 고정하여 기존 코드를 그대로 사용할 수 있습니다.
# v3 버전으로 명시적 설치
npm install -D tailwindcss@3 postcss autoprefixer
이후 package.json에서 "tailwindcss": "^3.4.0"과 같이 v3 버전으로 잘 고정되었는지 확인합니다.
Deep Dive
Tailwind CSS v4는 성능 향상과 개발자 경험 개선을 위해 많은 것을 바꾸었습니다. 가장 눈에 띄는 것은 tailwind.config.js의 제거입니다. 이제 테마 커스텀이나 유틸리티 추가는 CSS 파일 내에서 @theme, @utility 디렉티브를 사용하여 처리하는 ‘CSS-first’ 구문을 사용합니다.
또한, v4부터는 프로젝트 내의 소스 파일을 자동으로 감지하므로 기존처럼 content 배열에 경로를 일일이 지정할 필요가 없어졌습니다. 만약 기존의 복잡한 tailwind.config.js를 당장 버리기 어렵다면, v4에서도 메인 CSS 파일에 @config "../../tailwind.config.js"; 디렉티브를 추가하여 하위 호환성을 유지할 수 있습니다. 단, 장기적으로는 CSS-first 설정으로 마이그레이션하는 것이 좋습니다.
Conclusion
node_modules 재설치 후 발생하는 Tailwind CSS의 PostCSS 에러는 v4 메이저 업데이트로 인한 구조적 변화 때문입니다. Vite 환경에서는 기존의 PostCSS 설정을 과감히 삭제하고 @tailwindcss/vite 플러그인을 사용하는 것이 가장 깔끔하고 성능이 좋습니다. 프로젝트의 일정과 상황을 고려하여 v4로 업그레이드할지, v3로 버전을 고정할지 결정하시기 바랍니다.