🚨 Tailwind + cva + clsx + twMerge 조합에서 커스텀 유틸리티가 적용되지 않을 때

🔗 프로젝트 - 롤링

1. 🚨 Tailwind + cva + clsx + twMerge 조합에서 커스텀 유틸리티가 적용되지 않을 때

2. 🚨 PropTypes에서 JSDoc으로 — React 19 타입 관리 트러블슈팅

3. 🚨 낙관적 업데이트 — 이모지 반응 UI 미반영 트러블슈팅

4. [코드잇 스프린트 FE 19기] 기초 프로젝트 - 롤링 회고

---

프로젝트에서 Button 컴포넌트를 만들던 중

Tailwind, cva, clsx, twMerge를 함께 사용하는 과정에서 문제가 발생했다.

1️⃣ 문제 상황

import { cva } from 'class-variance-authority';
import { cn } from '@/utils/style';

const Button = ({
  children,
  type = 'button',
  style = 'primary',
  size,
  full = false,
  ...props
}) => {
  const buttonVariants = cva(
    'flex items-center justify-center rounded-md cursor-pointer',
    {
      variants: {
        style: {
          primary: 'bg-purple-600 text-white',
          secondary:
            'bg-white border border-solid border-purple-600 text-purple-700',
          outlined:
            'bg-white border border-solid border-gray-300 text-gray-900',
        },
        size: {
          s: 'h-[28px]',
          m: 'h-[36px]',
          l: 'h-[40px]',
          xl: 'w-[280px] h-[56px] rounded-2xl text-18-bold',
        },
        full: {
          true: 'w-full',
        },
      },
    }
  );

  return (
    <button
      className={cn(buttonVariants({ size, full, style }))}
      type={type}
      {...props}>
      {children}
    </button>
  );
};

export default Button;

• text-18-bold → 커스텀 폰트 유틸리티
• text-purple-700 → Tailwind 색상 유틸리티
• cn() → 내부적으로 clsx + twMerge 조합 사용

위와 같이 코드를 작성했는데, 화면에서 폰트 크기는 적용되지만 색상이 적용되지 않는 문제가 발생하였다.

 

2️⃣ 원인 분석

이 문제는 cn 유틸 함수 내부에서 사용 중인 twMerge() 때문이었다.

컬러와 커스텀 유틸리티가 모두 text라는 접두사를 사용하고 있었기 때문에,

마지막에 적용된 text-18-bold가 text-purple-700을 덮어써버린 것이 원인이었다.

 

3️⃣ 해결 방법

커스텀 유틸리티의 접두사를 text 대신 font로 변경하였다.

@utility font-28-bold {
  font-size: var(--text-28);
  line-height: var(--leading-28);
  font-weight: 700;
}

변경 후의 Button 컴포넌트는 아래와 같다.

import { cva } from 'class-variance-authority';
import { cn } from '@/utils/style';

const Button = ({
  children,
  type = 'button',
  style = 'primary',
  size,
  full = false,
  ...props
}) => {
  const buttonVariants = cva(
    'flex items-center justify-center rounded-md cursor-pointer',
    {
      variants: {
        style: {
          primary: 'bg-purple-600 text-white',
          secondary:
            'bg-white border border-solid border-purple-600 text-purple-700',
          outlined:
            'bg-white border border-solid border-gray-300 text-gray-900',
        },
        size: {
          s: 'h-[28px] font-14-regular',
          m: 'h-[36px] font-16-medium',
          l: 'h-[40px] font-16-regular',
          xl: 'w-[280px] h-[56px] rounded-2xl text-18-bold',
        },
        full: {
          true: 'w-full',
        },
      },
    }
  );

  return (
    <button
      className={cn(buttonVariants({ size, full, style }))}
      type={type}
      {...props}>
      {children}
    </button>
  );
};

export default Button;

이제는 원하는 대로 스타일이 잘 적용되었다. 🎉

 

4️⃣ 정리

• clsx + twMerge 조합을 사용할 때 커스텀 유틸리티 접두사가 Tailwind 기본 클래스와 겹치면 예상치 못한 덮어쓰기 문제가 발생할 수 있다.