React+Vite, TailwindCSS Cannot apply unknown utility class 오류 해결

Ollin·2025년 1월 25일

삽질일지

목록 보기

1/3

TailwindCSS를 사용하면서 개발 환경을 설정하던 중 Cannot apply unknown utility class: bg-background와 같은 오류를 만났습니다.
이 오류로 인해 TailwindCSS가 정상적으로 빌드되지 않았습니다.

마치 라잌 전쟁의 서막... '설정 하나 수정하면 끝나겠지'라는 순진한 생각은 금세 산산조각 나고, 끝없는 디버깅의 늪에 빠져버렸습니다. 쉽지 않네요...ㅋㅋ

💡 문제 상황

Error: Cannot apply unknown utility class: bg-background

이 오류는 TailwindCSS가 bg-background와 같은 유틸리티 클래스를 생성하지 못했음을 의미합니다. 프로젝트에서 CSS 변수(--background)를 기반으로 한 색상 설정을 확장했지만, Tailwind가 이를 제대로 인식하지 못한 상태였습니다.

background뿐만이 아닌 border-border, text-foreground도 인식하지 못했습니다.

🔍 시도했던 방법들

본격 삽질 시작..ㅎ

1️⃣ TailwindCSS 공식 문서에 확인 및 설정

TailwindCSS 공식 문서에서는 Vite와 TailwindCSS를 통합하기 위해 @tailwindcss/vite 플러그인을 사용하는 것을 권장하고 있습니다. 이에 따라 설정 파일을 작성했습니다.

// vite.config.ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
});

위 설정을 적용했음에도, Cannot apply unknown utility class 해결하지 못했습니다.

2️⃣ TailwindCSS 설정 확인 및 CSS 변수 확인

tailwind.config.js

module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx,css}'],
  theme: {
    extend: {
      colors: {
        background: 'hsl(var(--background, 0 0% 100%))',
      },
    },
  },
};

CSS 변수 확인

:root {
  --background: 0 0% 100%;
}

body {
  @apply bg-background;
}

원래부터 이렇게 작성되어있었지만 분명 문제가 있을 것 같아 굉장히 많이 확인했지만 해당 코드에는 문제가 없었습니다.

3️⃣ TailwindCSS 다운그레이드

npm install tailwindcss@3.4.17

다운그레이드 후, index.css 파일을 다시 빌드한 결과 빌드는 성공적으로 완료
→bg-background 클래스가 output.css에 생성됐지만 브라우저에서 확인했을 때, 여전히 Cannot apply unknown utility class: bg-background 오류가 발생, 500 Internal Server Error가 발생
→ 결국index.css 파일을 제대로 로드하지 못했습니다.

# 빌드 명령어
npx tailwindcss -i ./src/index.css -o ./dist/output.css --minify --verbose

/* 빌드 결과 */
.bg-background {
  background-color: hsl(0, 0%, 100%);
}

하지만 브라우저에서 확인했을 때, 여전히 Cannot apply unknown utility class: bg-background 오류가 있었고 500 Internal Server Error가 발생하며 index.css 파일을 제대로 로드하지 못했습니다.

4️⃣ 구글링 후 같은 오류 해결 방법 시도

프로젝트 루트에 tailwind.config.js와 tailwind.config.ts 파일이 공존할 경우, 하나를 삭제해야 한다는 내용을 확인
→ 중복된 파일이 없었습니다..
Next.js 환경에서 border-border와 같은 사용자 정의 클래스가 컴파일되지 않을 때 @layer utilities에서 정의 여부를 확인하라는 내용을 확인
→ index.css에서 사용자 정의 클래스를 직접 정의했지만, bg-background 문제와는 관련이 없었습니다.

🛠 최종 해결 방법

1️⃣ TailwindCSS 다운그레이드

TailwindCSS 최신 버전(4.0.0) 대신 3.4.17 버전을 사용
→ 해결 후 최신버전 설치했더니 오류 발생

npm install tailwindcss@3.4.17 autoprefixer@latest postcss@latest

2️⃣ vite.config.ts 파일 수정

기존 코드에서 @tailwindcss/vite 플러그인을 제거하고, TailwindCSS와 Autoprefixer를 PostCSS 플러그인으로 직접 추가했습니다.

// 기존 코드
import path from 'path';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

// 수정 코드
import path from 'path';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
import tailwindcss from 'tailwindcss';
import autoprefixer from 'autoprefixer';

export default defineConfig({
  logLevel: 'info',
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  css: {
    postcss: {
      plugins: [tailwindcss, autoprefixer],
    },
  },
});