Tailwind CSS 클래스 적용 오류 해결: 스타일이 보이지 않을 때 확인할 것

Tailwind 클래스가 안 먹을 때 먼저 확인할 순서

Tailwind CSS 클래스가 적용되지 않는 문제는 대부분 설치 연결, content 경로, 동적 클래스 작성 방식, 설정 변경 후 재시작, CSS 우선순위 중 하나에서 발생합니다. 막연히 코드를 다시 쓰기보다 Tailwind가 실제 파일을 읽고 클래스를 생성하는 흐름을 기준으로 하나씩 좁혀가면 빠르게 원인을 찾을 수 있습니다.

Tailwind 클래스가 적용되지 않는 대표 원인
설치와 전역 CSS import 먼저 확인하기
content 경로와 파일 확장자 점검하기
동적 클래스가 감지되지 않는 이유
커스텀 색상과 설정 변경 후 재시작 확인하기
CSS 우선순위와 클래스 충돌 확인하기
마지막 체크리스트

Tailwind 클래스가 적용되지 않는 대표 원인

Tailwind 클래스 오류 원인 진단: 파일 저장 content scan class 추출 흐름

Tailwind CSS에서 className="bg-blue-500 text-white"처럼 클래스를 썼는데 화면이 그대로라면 먼저 증상을 나눠봐야 합니다. 모든 Tailwind 클래스가 안 먹는지, 특정 색상만 안 먹는지, 조건부로 만든 클래스만 빠지는지에 따라 확인할 위치가 달라집니다.

전체가 안 먹는다면 전역 CSS 연결이나 Tailwind 설정 문제가 많습니다. 일부 파일에서만 안 먹는다면 content 경로에 해당 폴더가 빠졌을 가능성이 큽니다. 특정 색상이나 반응형 클래스만 안 보인다면 오타, 커스텀 설정, CSS 우선순위, 브라우저 캐시까지 함께 봐야 합니다.

중요한 기준은 Tailwind가 런타임에 클래스를 즉석에서 만드는 도구가 아니라는 점입니다. Tailwind는 빌드 과정에서 프로젝트 파일을 훑고, 발견한 클래스 이름을 기준으로 CSS를 생성합니다. 그래서 설정 경로와 문자열 형태가 생각보다 중요합니다.

설치와 전역 CSS import 먼저 확인하기

가장 먼저 볼 것은 Tailwind CSS가 프로젝트에 실제로 연결되어 있는지입니다. Next.js라면 보통 app/globals.css 또는 styles/globals.css 같은 전역 CSS 파일이 있고, 이 파일이 루트 레이아웃이나 앱 진입점에서 import되어야 합니다.

프로젝트 버전과 설치 방식에 따라 CSS 작성 방식은 다를 수 있지만, 핵심은 전역 CSS 파일이 빌드에 포함되어야 한다는 점입니다. 파일 안에 Tailwind 관련 import나 지시문이 있어도 그 CSS 파일 자체를 앱에서 불러오지 않으면 화면에는 아무 변화가 없습니다.

// app/layout.tsx 예시
import './globals.css';

export default function RootLayout({ children }) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  );
}

이 단계에서는 복잡한 설정을 보기 전에 아주 단순한 클래스부터 테스트하는 편이 좋습니다. 예를 들어 버튼에 bg-red-500, text-white, p-4를 직접 넣고 색상과 여백이 바뀌는지 확인합니다.

content 경로와 파일 확장자 점검하기

content 설정은 Tailwind가 어떤 파일을 읽을지 알려주는 목록입니다. 여기에 실제 컴포넌트가 들어 있는 폴더나 확장자가 빠지면, 코드에 클래스를 써도 Tailwind가 그 클래스를 발견하지 못합니다.

Next.js 프로젝트에서 app 폴더를 쓰는데 설정에는 pages만 들어 있거나, 컴포넌트를 src/components에 두었는데 src 경로가 빠진 경우가 흔합니다. .tsx 파일을 쓰는데 확장자 목록에 tsx가 없는 경우도 확인해야 합니다.

// tailwind.config.js 예시
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

설정을 고친 뒤에는 개발 서버를 재시작하는 것이 안전합니다. 설정 파일은 일반 컴포넌트 코드처럼 항상 즉시 반영되지 않을 수 있기 때문입니다.

동적 클래스가 감지되지 않는 이유

Tailwind 입문자가 자주 만나는 문제는 동적 클래스입니다. 예를 들어 `bg-${color}-500`처럼 문자열을 조합하면 보기에는 Tailwind 클래스처럼 보이지만, 빌드 시점에는 완성된 클래스 이름이 코드에 그대로 존재하지 않습니다. 그러면 Tailwind가 bg-red-500이나 bg-blue-500을 생성해야 한다는 사실을 모를 수 있습니다.

// 피하는 편이 좋은 예시
const className = `bg-${color}-500 text-white`;

// 권장 예시: 가능한 값을 명시적으로 매핑
const colorClass = {
  red: 'bg-red-500',
  blue: 'bg-blue-500',
  green: 'bg-green-500',
}[color];

가능한 클래스 목록이 정해져 있다면 객체나 조건문으로 완성된 클래스 이름을 코드에 남기는 방식이 좋습니다. 사용자 데이터처럼 값의 범위가 넓다면 Tailwind 설정의 safelist를 검토할 수 있지만, 모든 색상을 무작정 넣는 방식은 CSS 크기를 키울 수 있어 필요한 범위만 지정하는 편이 낫습니다.

커스텀 색상과 설정 변경 후 재시작 확인하기

커스텀 색상을 추가했는데 bg-brand-500이 적용되지 않는다면 이름이 설정과 정확히 맞는지 확인합니다. theme.extend.colors.brand에 넣었는지, 색상 단계가 500으로 존재하는지, 클래스 이름에 오타가 없는지 봐야 합니다.

Tailwind 설정 파일을 수정한 뒤 개발 서버를 그대로 두면 변경사항이 늦게 반영되거나 감지되지 않는 경우가 있습니다. 이때는 서버를 끄고 다시 실행한 뒤, 브라우저 새로고침과 캐시까지 확인합니다. 특히 설정 파일 이름이나 경로를 바꿨다면 재시작은 거의 필수 점검에 가깝습니다.

CSS 우선순위와 클래스 충돌 확인하기

Tailwind 클래스는 생성되었는데 화면에서 보이지 않는 경우도 있습니다. 이때는 브라우저 개발자 도구에서 해당 요소의 스타일을 직접 확인해야 합니다. 기존 CSS 파일의 선택자가 더 강하거나, 컴포넌트 라이브러리 스타일이 뒤에서 덮거나, style 속성의 inline style이 우선 적용될 수 있습니다.

!important를 바로 붙이는 것은 마지막 수단에 가깝습니다. 먼저 어떤 CSS가 덮고 있는지 확인하고, 클래스 순서, 선택자 범위, 전역 CSS 위치를 정리하는 편이 좋습니다. Tailwind끼리 충돌하는 경우에는 같은 속성의 클래스가 중복으로 들어가지 않았는지도 봅니다.

마지막 체크리스트

Tailwind 클래스 오류 해결 체크리스트: 문자열 조합 주의 safelist 고려 조건부 class 분리 흐름

정리하면 먼저 전역 CSS가 앱에 import되었는지 확인합니다. 다음으로 content 경로에 실제 파일 위치와 확장자가 들어 있는지 봅니다. 그다음 동적 문자열로 클래스 이름을 조합하고 있지 않은지, 커스텀 색상 이름이 설정과 맞는지, 설정 변경 후 개발 서버를 재시작했는지 확인합니다.

마지막으로 개발자 도구에서 해당 클래스가 CSS로 생성되었는지, 생성되었는데도 다른 스타일에 덮이고 있는지 확인합니다. 이 순서대로 보면 “Tailwind가 안 된다”는 넓은 문제를 설치 문제, 설정 문제, 작성 방식 문제, 우선순위 문제로 나눠서 처리할 수 있습니다.

같이 읽으면 좋은 글

이 글이 마음에 드세요?

RSS 피드를 구독하세요!