Tailwind CSS 설정 중 만난 오류들, 이렇게 해결했어요!

React + Vite + Tailwind CSS 환경을 셋업하면서 몇 가지 오류를 만났습니다.
초보자라면 충분히 당황할 수 있는 문제들이라, 저처럼 삽질(?)하지 않도록 정리해봅니다.
세 가지 주요 오류와 해결 방법을 단계별로 공유합니다.

---

🧱 1. 패키지 버전 문제 – 존재하지 않는 버전!

처음 package.json을 살펴보니 다음과 같은 비정상적인 버전들이 있었습니다.

"react": "^19.1.0",
"tailwindcss": "^4.1.6"

 

❌ 문제점:

• React의 최신 안정 버전은 v18.x
• Tailwind CSS의 안정 버전은 v3.x

🛠️ 해결 방법:

버전을 다음처럼 수정하거나, 아래 명령어로 다시 설치했습니다:

npm install react@18 react-dom@18
npm install -D tailwindcss@latest postcss autoprefixer

---

📄 2. 입력 파일 문제 – Tailwind가 뭘 처리해야 할지 모른다!

npx tailwindcss build 명령어 실행 시 이런 에러가 떴습니다:

[deprecation] Running tailwindcss without -i, please provide an input file.

 

❌ 문제점:
Tailwind는 우리가 만든 CSS 파일(@tailwind base; 등 포함)을 어떤 파일로 처리할지 몰랐던 거죠.

 

🛠️ 해결 방법:

index.css 파일(또는 src/index.css)을 만들고 다음과 같이 작성했습니다:

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

 

그 후, Vite 프로젝트에서 이 파일을 main.jsx에서 import:

import './index.css';

---

📂 3. 설정 파일 문제 – content 배열 비어 있음

tailwind.config.js 파일의 기본 템플릿은 이렇게 생겼습니다:

 

module.exports = {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

 

❌ 문제점:
content 배열이 비어 있어서 Tailwind가 어떤 파일을 스캔해야 할지 몰랐습니다.
즉, 우리가 작성한 .jsx나 .tsx 파일들을 무시하고 있었던 겁니다.

 

🛠️ 해결 방법:

다음처럼 src 폴더 내 모든 React 관련 파일을 감시하도록 설정합니다:

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

---

✅ 현재 설정 요약

항목	상태
✅ tailwindcss 최신 버전 설치 완료	OK
✅ index.css에 Tailwind 디렉티브 추가	OK
✅ tailwind.config.js에 content 경로 지정	OK
✅ 컴포넌트에서 클래스 사용 시 정상 반영	OK

 

---

✍️ 마무리하며

Tailwind CSS는 정말 강력한 도구지만, 처음 설정할 땐 몇 가지 함정이 숨어 있습니다.
이번에 직접 겪어보고 나니, 작은 실수 하나로 한참을 헤맬 수 있다는 걸 다시 느꼈습니다.

이 글이 저처럼 삽질하지 않도록 도와주는 작은 디버깅 참고서가 되면 좋겠습니다 😊