twMerge 커스텀 클래스 스타일 충돌 해결

약속 프로젝트에서는 Tailwind CSS를 활용해 공통 컴포넌트를 스타일링하며, twMerge, clsx, 그리고 cva를 조합하여 variant 기반 스타일링과 클래스 중복 제거를 효율적으로 관리하고 있다. 이 중 twMerge는 Tailwind 클래스 간 충돌을 감지하고, 우선순위에 따라 가장 마지막에 정의된 클래스를 병합해주는 유틸리티로, 다크모드 및 반응형 클래스 등 다양한 변형이 많은 Tailwind 환경에서 유용하게 활용된다.

 

해당 프로젝트에서는 디자인 시스템에 기반해 다음과 같이 text-head1, text-head2 등의 커스텀 타이포그래피 유틸 클래스를 정의하여 사용하고 있다.

  --text-head1--line-height: 52px;
  --text-head1--letter-spacing: -0.6px;
  --text-head1--font-weight: 800;
  --text-head2: 36px;
  --text-head2--line-height: 46px;
  --text-head2--letter-spacing: -0.6px;
  --text-head2--font-weight: 800;
  --text-head3: 36px;
  --text-head3--line-height: 46px;
  --text-head3--letter-spacing: -0.6px;
  --text-head3--font-weight: 800;

 

 

그러나 이처럼 text- 접두사를 사용하는 클래스들은 Tailwind의 기본 텍스트 색상 클래스(text-white, text-gray-700 등)와 동일한 접두사를 사용하기 때문에, twMerge는 이를 동일한 class group으로 인식한다. 이로 인해 병합 시 마지막으로 작성된 클래스만 남기고, 나머지 클래스는 제거되는 충돌 현상이 발생한다.

<p className="text-white text-head2">hello world</p> // text-head2로 병합

 

 

이 때 twMerge에서 제공하는 extendTailwindMerge API를 사용하면 twMerge의 병합 규칙 확장을 통하여 커스텀 타이포그래피 클래스와 기본 텍스트 컬러 클래스가 안정적으로 공존할 수 있게 한다.

 

아래와 같이 프로젝트에서 사용하는 커스텀 text-* 클래스들을 명시적으로 font-size class group에 등록하면 문제를 해결할 수 있다.

import { ClassValue, clsx } from 'clsx'
import { extendTailwindMerge } from 'tailwind-merge'

const customTwMerge = extendTailwindMerge({
  extend: {
    classGroups: {
      'font-size': [
        'text-head1',
        'text-head2',
        'text-head3',
        'text-head4',
        'text-head5',
        'text-head6',
        'text-subhead1',
        'text-subhead2',
        'text-subhead3',
        'text-body1',
        'text-body2',
        'text-caption1',
      ],
    },
  },
})

export function cn(...inputs: ClassValue[]) {
  return customTwMerge(clsx(inputs))
}