/
/

RoomE / TailwindCSS v.4 충돌

프로젝트 기록tailwindCSS 4.0
avatar
미슬랭
2025.02.19
·
5 min read
3496

오늘의 이슈

테일윈드 버전 업데이트로 인한 오류를 겪었다.

테일윈드 css 커스텀이 필요해서 기존과 동일하게 tailwind.config.js 를 사용해서 box-shadow, gradient 등을 커스텀했는데, 해당 커스텀 코드가 동작하지 않는 문제가 있었다.

이미 테일윈드 내장 postcss와 추가로 설치한 postcss의 충돌 문제를 경험한 터라 v.4 업데이트 문제일거라고 예상은 했는데, 공식 문서를 꼼꼼하게 보지 않아서 이 문제를 해결하기까지 너무 많은 시간을 소모했다.

과정

공식 문서와 velog, AI를 통해 많은 자료를 검색해봤지만 4.0으로 업데이트 된지 얼마 되지 않아 자료가 많지 않았다.

해결 방안

공식 문서를 잘못 해석해서 발생한 이슈였다. 커스텀 관련 정보를 찾고 싶어서 ‘custom’이라는 키워드로 검색 후 다음 문서를 참고했는데

https://tailwindcss.com/docs/adding-custom-styles

내가 찾는 정보는 여기에 있는 정보였다.

https://tailwindcss.com/docs/theme

테일윈드 공식 문서에서 제공하는 커스텀에 대한 정보는 테일윈드 기본값을 사용자 정의(커스텀)하는 방식에 대한 안내였다.

내가 생각한 개념은 디자인 토큰이라 디자인 토큰 관련으로 검색을 했어야 하는데, 자료 검색시에 custom으로만 검색해서 정보가 더 한정적이었던 것 같다.

기존 버전에서 tailwind.config.js 로 설정했던 커스텀 코드는 v.4부터는 css에서 다음과 같이 @theme 디렉티브를 사용해 변수로 정의할 수 있다.

@import "tailwindcss";
@theme {
  --color-mint-500: oklch(0.72 0.11 178);
}

테일윈드에서 지원하는 다음 네임 스페이스를 사용해 커스텀하면 된다.

Namespace Utility classes

--color-*

Color utilities like bg-red-500, text-sky-300, and many more

--font-*

Font family utilities like font-sans

--text-*

Font size utilities like text-xl

--font-weight-*

Font weight utilities like font-bold

--tracking-*

Letter spacing utilities like tracking-wide

--leading-*

Line height utilities like leading-tight

--breakpoint-*

Responsive breakpoint variants like sm:*

--container-*

Container query variants like @sm:* and size utilities like max-w-md

--spacing-*

Spacing and sizing utilities like px-4, max-h-16, and many more

--radius-*

Border radius utilities like rounded-sm

--shadow-*

Box shadow utilities like shadow-md

--inset-shadow-*

Inset box shadow utilities like inset-shadow-xs

--drop-shadow-*

Drop shadow filter utilities like drop-shadow-md

--blur-*

Blur filter utilities like blur-md

--perspective-*

Perspective utilities like perspective-near

--aspect-*

Aspect ratio utilities like aspect-video

--ease-*

Transition timing function utilities like ease-out

--animate-*

Animation utilities like animate-spin

  @theme {
	  --drop-shadow-book: 10px 4px 10px rgba(78, 122, 207, 0.15);
	  --drop-shadow-logo: 0px 4px 4px rgba(78, 122, 207, 0.15);
	  --drop-shadow-modal: 0px 10px 10px rgba(38, 86, 205, 0.3);
	 }

해당 코드가 업데이트 된 방식으로 적용해본 코드이다. shadow-book과 같이 사용할 수 있다.

정리 및 느낀 점

개념만 이해하고 있으면 정확한 명칭은 별로 중요하지 않다고 생각했었는데, 적절한 검색 결과를 얻기 위해서는 정확한 키워드 선정의 중요성이 중요하다는 점을 인식하게 됐다.

이번 프로젝트 세팅 때 테일윈드를 최신 버전으로 세팅해두고, 간단히 변경점을 정리한 기술 블로그를 읽는 것으로 대신 했더니 오히려 문제 해결에 더 오래 걸린 것 같아서, 앞으로는 새로운 기술이나 새 버전을 도입할 때 공식 문서 먼저 정독하는 습관을 들여야겠다.

- 컬렉션 아티클