[트러블 슈팅] 갑자기 Tailwind가 적용되지 않는다...?

Next.js 프로젝트에서 Tailwind CSS를 적용했는데, 일부 컴포넌트에서만 스타일이 적용되지 않는 문제가 발생했다. (아래처럼...)

항상 느끼지만 개발을 하면 항상 원하는 결과물이 나오지 않는다.

그래서 난 문제상황에 직면하면 항상 가설을 세우고 검증하면서 트러블 슈팅을 하는데, 정확히 어떠한 과정을 통해 문제를 해결하는지 공유하면 좋을 거 같아 글을 남긴다.

트러블슈팅 과정

처음에는 Tailwind Grid 속성(className)을 잘못 부여해서 생긴 문제인 지 알았는데, 그런 문제는 아니었다. 따라서 진행한 트러블 슈팅 과정은 아래와 같다.

Card 컴포넌트의 Grid 스타일이 적용 이슈 발생

처음에는 TechStack.tsx 내부에서 Card 컴포넌트를 그리드로 배치했는데, 아무리 해도 Grid 스타일이 적용되지 않았다.

<div className="grid grid-cols-2 gap-4">
  {TechStackInfo.map((tech) => (
    <Card key={tech.id} tech={tech} />
  ))}
</div>

처음에는 map 문제인가 싶어서 반복문을 없애고 개별적으로 Card를 렌더링해봤는데 그대로였다. 따라서 부모 측에서 확인해보고자 했다.

page.tsx에서 직접 Card를 렌더링

최상위 page.tsx에서 직접 Card를 렌더링을 해봤다.

import { Card } from "@/section/techStack/_components/Card";

export default function Home() {
  return (
    <div className="grid grid-cols-2 gap-4">
      <Card tech="JavaScript" />
      <Card tech="TypeScript" />
    </div>
  );
}

하지만 여전히 스타일이 전혀 적용되지 않고 있었다.

Grid 컴포넌트를 아예 제거하고 page.tsx에서 직접 스타일 적용

Grid 컴포넌트를 사용하지 않고, 직접 스타일을 적용하니 원하던 뷰가 나왔다.

export default function Home() {
  return (
    <div className="grid grid-cols-5 gap-4 bg-gray-50 p-8 w-full h-full">
      <span className="bg-white p-4 text-center shadow-md">JavaScript</span>
      <span className="bg-white p-4 text-center shadow-md">TypeScript</span>
      <span className="bg-white p-4 text-center shadow-md">React</span>
    </div>
  );
}

사용 중인 라이브러리 제거

혹시 page.tsx 상위에서 사용중인 혹시 Framer Motion 애니메이션 라이브러리가 Tailwind 적용을 방해하나 싶어서
를 감싸고 있는 부분을 주석 처리하고 Card를 가져왔지만, 여전히 실패했다.

tailwind.config.ts 확인

이런 가설 및 검증 과정을 통해서, 최종적으로 든 생각은 같은 렌더링 과정을 거치는데 스타일링이 적용되지 않는다는 것은 설정 부분에서 문제가 있을 가능성이 높다는 결론을 내렸다.

따라서 관련 자료를 살펴보았고, Next.js에서 Tailwind CSS는 정적인 CSS 파일을 생성하는 것이 아니라, JIT(Just-In-Time) 엔진을 사용해 동적으로 필요한 CSS만 생성한다는 점을 알게됐다.

_tailwind.config.ts의 content 배열에 지정된 경로를 기반으로 사용된 클래스를 탐색하는데, 특정 파일 경로가 누락되면 해당 컴포넌트에서 사용된 Tailwind 클래스가 감지되지 않으며, 결과적으로 스타일이 적용되지 않는다

또 위와 같은 아티클을 접할 수 있었고, 설정을 다시 확인한 결과 내 설정에는 TechStack.tsx가 속한 ./src/section/ 경로가 누락되어 있었다.

  "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
  "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
  "./src/app/**/*.{js,ts,jsx,tsx,mdx}",

결론

아래와 같이 해당 파일이 속한 경로를 추가하면서 트러블 슈팅을 할 수 있었다.

  // tailwind.config.ts 수정
  content: [
  "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
  "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
  "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
  "./src/section/**/*.{js,ts,jsx,tsx,mdx}", // 추가
]

Tailwind는 tailwind.config.ts의 content 설정에서 지정한 파일만 감지해서 스타일을 생성한다고 배울 수 있었다.

Tailwind를 통한 스타일링이 특정 파일에서 적용되지 않으면 tailwind.config.ts에 해당 파일이 속한 경로를 추가해주면 된다.