달라진 TailwindCSS v4 커스텀하기

 

TailwindCSS가 v4로 올라오면서 전반적인 설정 방식부터 유틸리티 클래스 커스터마이징 방식이 달라졌습니다. 특히 "CSS-first" 접근 방식은 기존 v3 사용자라면 익숙한 설정 방식과 완전히 다르기 때문에, 처음 마주하면 당황스러운 경험을 할 수 있습니다.

저도 새로운 레파지토리를 세팅할때 달라진 방식을 경험하면서(CSS만으로 유틸리티를 커스터마이징 하는 법) v4에 적응했던 경험을 공유해보고자 합니다. 

 

tailwindCSS v3 vs v4 뭐가 달라졌을까

 

1. JS에서 CSS로

기존 v3까지는 tailwind.config.js 혹은 .ts 파일을 만들어 테마 값을 확장하거나 플러그인을 추가했습니다. 하지만 v4는 이 설정 자체를 CSS 파일 안에서 직접 정의할 수 있습니다. 예전처럼 JS 파일에 theme.extend를 넣는 대신, 아래와 같이 CSS에 @theme지시어로 색상, spacing, breakpoint 등을 선언하면 됩니다.

@theme {
  --color-avocado-500: oklch(0.8 0.15 120);
  --spacing-fluid: clamp(1rem, 2vw, 2rem);
}

 

이후엔 .bg-avocado-500 이런 식으로 그대로 사용이 가능합니다.

 

📄 공식 문서

Theme variables - Core concepts

 

 

2. 빌드 엔진이 Rust 기반으로 -> 성능 대폭 향상

Tailwind v4는 Rust로 빌드 엔진을 갈아엎었다고 합니다. 성능은 체감될 정도로 엄청 빨라졌는데요. 전체 빌드는 최대 5배, 핫 리로드는 100배 빨라졌다고 합니다.

 

실제로 개발중에 저장만 하면 바로 스타일이 반영되는 느낌으로 정말 부드러운 체감을 느낄 수 있었습니다.

 

 

3. CSS 변수 + 최신 기능 도입

기본 색상, 여백, 폰트 사이즈 등 거의 모든 토큰이 CSS 변수화되었습니다. 예를 들어 --color-blue-500 이런 식으로 정의돼서 JavaScript나 다른 CSS에서도 재활용이 가능합니다.

// React에서 사용 예시
<div style={{ backgroundColor: 'var(--color-blue-500)' }} />

 

또한 Cascade Layers, @property, color-mix() 와 같은 최신 CSS 기능도 적극 도입이 돼서, Tailwind가 더 이상 CSS 프레임워크가 아니라 거의 CSS 런타임 수준으로 느껴집니다.

 

참고 : https://tailwindcss.com/blog/tailwindcss-v4

Tailwind CSS v4.0

 

 

4. 유틸리티 클래스도 직접 정의 가능

이게 핵심. 기존엔 JS 설정 파일에서 plugind으로 커스텀 유틸리티를 추가했지만, 이제는 CSS에서 바로 정의가 가능해졌습니다.

@utility content-auto {
  content-visibility: auto;
}

 

이렇게 하면 <div className="content-auto"> 처럼 바로 사용할 수 있습니다. 

 

 

직접 CSS에서 유틸리티를 만들어보자

 

1. 스크롤바 숨기기

@utility scrollbar-hidden {
  &::-webkit-scrollbar {
    display: none;
  }
}

 

이런식으로 css 파일에 정의를 하고 클래스만 써주면 끝납니다.

 

<div class="scrollbar-hidden">스크롤바 없는 영역</div>

 

 

2. 탭 너비 유틸리티 만들기

@theme {
  --tab-size-2: 2;
  --tab-size-4: 4;
  --tab-size-github: 8;
}

@utility tab-* {
  tab-size: --value(--tab-size-*);
}

 

사용 예시:

<pre class="tab-4">  들여쓰기 확인</pre>

 

 

여기서 --value()는 v4에서 새로 도입된 함수로, 테마에서 매칭되는 값을 가져옵니다.

 

참고

Functions and directives - Core concepts

 

 

 

기존 프로젝트에서 v4로 마이그레이션하려면?

v3에서 쓰던 config 파일은 여전히 쓸 수 있습니다. 다만 @config 지시로 명시를 해야 tailwind가 인식을 합니다.

@config "./tailwind.config.ts";

 

그러나 Tailwind Lab은 CSS-first 방식을 공식 권장하고 있으니, 신규 프로젝트는 가능하면 v4 방식에 익숙해지는 것이 좋을 것 같다는 생각이 듭니다.

 

 

결론

Tailwind CSS v4는 단순한 마이너 업데이트가 아닌 것 같습니다. 설정의 중심을 JS에서 CSS로 옮긴 패러다음의 전환입니다. 개발자 입장에서 이는 복잡한 설정 파일 없이도 디자인 시스템을 코드로 직접 선언하고, 커스터마이징을 더 직관적으로 제어할 수 있게 되었다는 뜻입니다.

 

기존에는 유틸리티나 테마를 바꾸려면 반드시 tailwind.config.js에서 정의하고, 그 설정이 빌드에 반영되도록 다시 돌려야 했습니다. 하지만 이제는 CSS 파일 안에서 유틸리티를 선언하고 테마 토큰을 직접 정의할 수 있습니다. 심지어 필요한 경우만 쏙쏙 골라서 작은 단위로 분리해 작성하는 것도 가능합니다. 덕분에 프로젝트 규모가 커져도 설정이 한 곳에 몰리지 않고, 의미 있는 방식으로 구조화할 수 있게 되었습니다.

 

이런 변화는 단순한 수준을 넘어서, 디자인 시스템을 코드 레벨에서 더 명확히 정의하고 관리할 수 있는 환경을 만들어 줍니다.