Tailwind CSS 적용하면서 알게 된 실전 팁과 실패 경험들

저도 처음에는 Tailwind CSS가 정말 편할 줄 알고 무작정 도입했는데, 생각보다 삽질을 많이 했어요. 클래스 이름이 너무 많고 헷갈려서 제대로 활용 못 하다가 시간이 꽤 지체되더라고요.

이 글에서는 제가 Tailwind를 프로젝트에 적용하면서 겪었던 실제 문제들과 그 해결 과정, 그리고 꼭 알았으면 하는 핵심 팁들을 차근차근 정리해봤어요. 같은 고민하시는 분들은 이 글 한 번만 읽어도 큰 도움 될 거예요.

개발 환경 / 버전 정보

저는 Tailwind CSS 3.3 버전을 사용했고, 개발은 React 18과 Vite 4 환경에서 진행했어요. 빌드 도구와 Node 버전은 각각 Node 18을 썼고, 패키지는 npm 9을 활용했어요.

저는 이렇게 적용했는데 처음에 많이 틀렸던 부분

사실 Tailwind가 워낙 범용적이어서 바로 쓸 수 있을 거라 생각했는데, 첫 번째 함수형 컴포넌트에 클래스 스타일 붙이면서 삽질한 게 많았어요. 특히 클래스를 조합할 때 띄어쓰기 실수로 중간에 클래스가 안 먹히는 경우가 자주 있었거든요.

예를 들어 이렇게 썼는데 의도대로 스타일이 안 나왔어요:

<div className="bg-blue-500text-white p-4">Hello</div>

잘 보시면 bg-blue-500과 text-white 사이에 띄어쓰기 누락으로 두 클래스가 합쳐져서 인식 안 된 거였어요. 이걸 몰라서 한참을 스타일이 안 바뀌는 줄 알고 구글링만 했죠.

핵심 구현 방법: 유틸리티 클래스 조합부터 반응형까지

Tailwind는 수백 개의 유틸리티 클래스를 조합해서 UI를 완성하는 방식인데, 제가 깨달은 건 클래스 이름은 반드시 띄어쓰기로 구분해야 한다는 점이에요. 그리고 JSX 안에서 클래스명을 너무 길게 적으면 가독성이 떨어지는데, 이를 해결하기 위해 클래스 이름을 배열로 관리하면서 join(' ') 하는 방식을 썼어요.

// 클래스 배열로 관리해서 가독성 높이기
const btnClasses = [
  'bg-blue-600',
  'hover:bg-blue-700',
  'text-white',
  'font-semibold',
  'py-2',
  'px-4',
  'rounded',
].join(' ');

function Button({ children }) {
  return <button className={btnClasses}>{children}</button>;
}

이렇게 하면 클래스가 길어도 각각 라인별로 의미를 바로 알 수 있어서 유지보수가 편해지고, 실수로 띄어쓰기 빠뜨리는 문제도 줄어드더라고요.

또한 반응형 디자인에서 자주 쓰는 sm:, md:, lg: 같은 접두어를 붙일 땐 항상 순서와 우선순위를 신경 써야 해요. 반응형 적용이 안 된 줄 알고 한참 헤맸던 것도 이 때문이었죠.

여기서 삽질했던 부분들: 실제 사례와 해결 과정

저는 특히 다음 세 가지 상황에서 크게 막혔는데, 공유할게요.

• 1. Tailwind 빌드 시 PurgeCSS 설정 누락: 클래스 이름을 동적으로 조합하면 빌드 결과에서 해당 클래스가 사라져 버려서 스타일이 적용 안 됐어요. 그래서 dev환경에선 잘 보이는데 프로덕션 빌드 후에 스타일이 사라지는 문제였죠.
• 2. 플러그인 버전 불일치: Tailwind 플러그인을 설치하면서 React 버전과 충돌이 났는데, 에러 메시지가 워낙 일반적이라 한참 고생했어요.
• 3. 커스텀 색상 변수 오타: tailwind.config.js에서 색상 커스터마이징 하다가 컬러 키를 잘못 붙여서 빌드는 문제 없지만 화면에 적용이 안 된 경우도 있었어요.

예를 들어 첫 번째 문제는 이렇게 동적 클래스를 쓸 때 생겼는데요:

const isActive = true;
const className = `bg-${isActive ? 'green' : 'red'}-500`;

return <div className={className}>상태 표시</div>;

이렇게 쓰면 PurgeCSS가 실제 클래스명을 미리 파악하지 못해서 bg-green-500이나 bg-red-500이 빌드에서 누락돼버렸는데, 저는 tailwind.config.js에 safelist 항목을 추가해서 직접 이 클래스들을 적어줘야 한다는 걸 몰라서 몇 시간을 헤맸습니다.

심화: 이것도 알면 개발이 더 편해져요

Tailwind를 잘 쓰기 위해서 PostCSS 설정과 PurgeCSS 옵션 조합을 공부하는 게 정말 중요해요. 빌드 최적화와 스타일 유지 사이에서 균형을 맞추는 게 생각보다 까다롭거든요. 그리고 VSCode 사용하시면 Tailwind IntelliSense 확장 설치는 필수로 추천해요. 클래스 이름 자동완성에 오타 방지 기능까지 있어서 생산성이 확 올라갑니다.

또 한 가지는 커스텀 테마 설계입니다. 기본 색상이나 폰트를 tailwind.config.js에서 직접 추가하는데, 이렇게 설정하면 나중에 클래스 쓸 때 키값으로 쉽게 쓸 수 있어서 코드가 훨씬 깔끔해져요.

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#1c92d2',
        secondary: '#f2f4f7',
      },
    },
  },
  plugins: [],
};

이러면 bg-primary처럼 개발자 의도에 맞는 클래스를 쉽게 적용할 수 있어서 실수도 줄이고 유지보수도 쉬워져요.

자주 물어보시는 것들

Q. 동적 클래스명을 쓸 땐 어떻게 해야 하나요?

A. Tailwind는 빌드 시 실제 코드에 있는 클래스 이름만 남기는 구조여서, 동적 조합은 빌드에서 사라질 위험이 큽니다. 따라서 tailwind.config.js의 safelist를 활용하거나 clsx 같은 라이브러리를 쓴 뒤 미리 가능한 클래스들을 전부 적어주는 방식을 써야 합니다.

Q. Tailwind 빌드 후 스타일이 갑자기 안 먹어요. 왜 그럴까요?

A. 보통 PurgeCSS 설정이 잘못됐을 때 이런 문제가 발생합니다. 특히 클래스명이 동적으로 생성되는 부분이 있으면 빌드 시 누락될 수 있으니, safelist 옵션에 반드시 포함해줘야 해요.

Q. VSCode에서 Tailwind 클래스 자동완성은 어떻게 설정하나요?

A. VSCode 확장 마켓플레이스에서 Tailwind CSS IntelliSense를 설치하세요. 설치 후 프로젝트 root에 tailwind.config.js가 있어야 작동합니다.

제가 Tailwind CSS를 도입하며 겪었던 시행착오들을 정리해보니, 결국 이런 사소한 부분들만 잘 관리해도 생산성과 코드 품질이 크게 좋아지더라고요. 더불어 이 경험 덕분에 스타일 작성에 드는 시간이 확 줄었고, 팀 협업 시 스타일 충돌도 줄일 수 있었습니다.