Tailwind CSS 설정 오류 해결기: Vite + React 환경에서 발생한 문제와 대처법

Tailwind CSS를 Vite + React + TypeScript 환경에 설정하는 과정에서 예상치 못한 오류를 여러 번 경험했습니다.
이 글에서는 제가 실제로 겪은 문제와, 그에 대한 해결 과정을 정리된 가이드 형식으로 공유합니다.
앞으로 비슷한 환경에서 설정하실 분들께 도움이 되길 바랍니다.

---

❗ 발생했던 문제들

1. PostCSS 플러그인 관련 에러
   • Error: Cannot find module 'postcss' 혹은 postcss.config.js not found 등의 메시지 발생
2. ES 모듈과 CommonJS 모듈 혼용 문제
   • 설정 파일(tailwind.config.js)에서 require 구문 사용 시 에러 발생
   • 또는 .js 파일에서 module.exports가 인식되지 않음
3. 설정 파일 확장자 문제
   • Vite는 기본적으로 ES 모듈을 사용하는데, 설정 파일은 CommonJS 방식이어서 충돌 발생

---

✅ 해결 방법

1. 설정 파일 확장자를 .cjs로 변경
   • tailwind.config.js → tailwind.config.cjs
   • postcss.config.js → postcss.config.cjs
   • CommonJS 방식으로 명확히 지정
2. 패키지 버전 고정 설치 (호환성 보장)

   npm install -D tailwindcss@3.3.0 postcss@8.4.31 autoprefixer@10.4.14

    
3.  설정 파일에서 module.exports 사용

// tailwind.config.cjs
module.exports = {
  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
}


// postcss.config.cjs
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

 

🧠 다음 프로젝트 때 참고할 프롬프트 팁

Tailwind 설정 시, 다음처럼 명확한 프롬프트 또는 초기 설정 기준을 잡아두면 시행착오를 줄일 수 있습니다.

예시 프롬프트:

"Vite + React + TypeScript + TailwindCSS를 설정할 건데, 설정 파일은 CommonJS 형식(.cjs)을 사용하고, TailwindCSS는 3.3.0 버전, PostCSS는 8.4.31 버전으로 고정해주세요. 그리고 App.tsx에서 바로 적용할 수 있게 예제도 포함해주세요."

---

⚠️ 주의사항 정리

• ✅ Vite는 기본적으로 ES 모듈(ESM)을 사용
  → 설정 파일에서 require를 쓰려면 CommonJS(.cjs) 확장자를 명시적으로 지정해야 함
• ✅ Node.js 버전은 18 이상 권장
  → 낮은 버전에서는 일부 최신 패키지와 충돌 발생 가능
• ✅ TailwindCSS와 PostCSS의 버전 호환성을 반드시 확인
  → 특히 오래된 글/문서 참고 시 주의!

---

✨ 마무리하며

Tailwind CSS는 정말 강력한 도구이지만, 초기 설정에서 한두 가지 문제만 삐끗해도 막히기 쉽습니다.
이번 경험을 통해 구체적인 설정 기준과 명확한 명령어, 확장자 지정이 얼마나 중요한지 체감했습니다.

앞으로도 이런 실제 에러와 해결 경험을 계속 기록하고 나누려고 합니다.
비슷한 이슈가 있으셨거나, 더 좋은 방법이 있다면 댓글로 공유해주세요! 🙌