[TailwindCSS] Thymeleaf에서 TailwindCSS 유틸리티 클래스가 적용되지 않는 문제 해결

😕 문제 상황

---

Spring Boot 프로젝트에서 Thymeleaf를 사용하며 TailwindCSS의 유틸리티 클래스(justify-between, text-center, bg-blue-500 등)가 적용되지 않는 문제가 발생했다.

특히 header 부분에서 justify-between 클래스를 추가했음에도 레이아웃이 기대한 대로 변경되지 않았다.

 

🔍 문제 원인

---

Tailwind CSS 빌드 파일 미생성 또는 갱신 문제

Tailwind CSS버전 3.0 이상에서는 기본적으로 JIT(Just-In-Time) 모드로 동작하며, 실제 HTML, JS 파일 등에서 사용된 유틸리티 클래스만을 기반으로 최종 CSS 파일을 생성한다.

• JIT 모드란? 필요할 때 즉시 CSS를 생성하여 성능을 최적화하는 방식으로, 설정된 content 경로에서 클래스를 탐색한다.
• 문제의 핵심: Tailwind CSS의 빌드 명령어를 실행하지 않으면 새로 추가한 클래스가 output.css에 포함되지 않는다.

즉, 내 상황에서는 빌드 명령어를 실행하지 않았거나, --watch 옵션을 주지 않으면 변경 사항이 실시간으로 반영되지 않기 때문에 해당 스타일들이 적용되지 않았던 것이다.

또한, Tailwind CSS는 tailwind.config.js 파일의 content 배열에 지정된 경로를 기준으로 유틸리티 클래스를 탐색하므로, content에 Thymeleaf 템플릿 경로를 포함하지 않으면, HTML 파일에 추가된 클래스를 감지할 수 없다.

 

🛠️ 해결 과정

---

1. TailwindCSS 빌드 명령어 확인 및 실행

package.json에 TailwindCSS 빌드 명령어를 다음과 같이 정의한다:

"scripts": {
  "build:css": "tailwindcss -i ./src/main/resources/static/css/tailwind.css -o ./src/main/resources/static/css/output.css --watch"
}

• -i : 입력 파일 경로 지정
• -o : 출력 파일 경로 지정
• --watch : 코드 변경 사항을 감지하여 실시간으로 빌드

Tip: --watch 옵션을 사용하지 않으면 코드 변경 후 매번 수동으로 빌드를 다시 해야 한다.

 

명령어 실행:

npm run build:css

 

 

2. tailwind.config.js의 content 설정 확인

앞서 언급한 대로 content 배열에 Thymeleaf 파일의 경로를 정확히 설정한다.

content: [
  "./src/main/resources/templates/**/*.html",
  "./src/main/resources/static/js/*.js"
]

작동 원리:

• Tailwind CSS는 content 경로에 지정된 파일의 코드를 분석하여 사용된 클래스만을 output.css에 포함시킨다.
• 이를 통해 불필요한 CSS가 제거되어 파일 크기가 최소화된다.

3. Thymeleaf 템플릿을 변경하고 나서 확인해야 할 것들

• TailwindCSS 클래스명은 반드시 output.css 파일에 포함되어야 한다
• 모든 설정을 올바르게 적용한 후, justify-between과 같은 TailwindCSS 유틸리티 클래스가 정상 작동함을 확인했다.