AI 소식2026-04-129 min

Tailwind v4 올렸다 — 설정 파일이 전부 사라졌다

Q: tailwind.config.js는 완전히 삭제해야 하나?

v4에서는 tailwind.config.js가 필요 없다. CSS 파일의 @theme 블록이 대체한다. 자동 마이그레이션 CLI가 변환을 처리하므로 수동으로 지울 필요는 없다.

Q: Oxide 컴파일러는 별도로 설치해야 하나?

별도 설치는 필요 없다. tailwindcss v4 패키지 안에 포함되어 있다. npm install tailwindcss@next 한 번으로 자동 활성화된다.

Q: v4에서 @tailwindcss/typography 같은 플러그인은 어떻게 쓰나?

CSS 파일에서 @plugin '@tailwindcss/typography'처럼 선언하면 된다. tailwind.config.js의 plugins 배열 대신 @plugin 지시어를 사용한다.

Q: 기존 Next.js 프로젝트를 v4로 올리는 데 얼마나 걸리나?

커스텀 플러그인이 없는 프로젝트 기준, npx @tailwindcss/upgrade 실행 포함 30분 안에 끝난다. 복잡한 플러그인이 있으면 수동 검증이 추가로 필요하다.

Q: v3 프로젝트를 지금 당장 v4로 올려야 하나?

서두를 필요는 없다. v3는 계속 지원된다. 신규 프로젝트나 빌드 속도가 병목인 상황이라면 v4가 맞다. 복잡한 커스텀 플러그인이 많으면 v3 유지가 더 안정적이다.

Tailwind CSS v4로 마이그레이션했다. tailwind.config.js가 없어지고 CSS 파일 하나로 설정이 끝난다. Rust 기반 Oxide 컴파일러로 빌드 속도가 5배 빨라졌다. v3에서 v4 전환 전 과정을 기록했다.

목차 (10)

설정 파일이 CSS로 들어왔다
@theme 문법 파고들기
Oxide 컴파일러가 속도를 바꿨다
v3에서 v4로 전환하는 순서
Next.js + PostCSS 설정 방법
바뀐 클래스명 체크리스트
커스텀 플러그인 대응
v3 vs v4 한눈에 비교
언제 올려야 하나
자주 묻는 질문

2026년 4월 · GoCodeLab

Tailwind CSS v4 마이그레이션 실전 가이드

Tailwind CSS v4가 정식 출시됐다. tailwind.config.js가 사라졌다. 설정을 CSS 파일 안에서 직접 쓰는 방식으로 바뀌었다. Next.js 프로젝트에 직접 적용해봤다. 결론부터 말한다 — 낯설지만 더 단순하다.

v3를 쓰던 프로젝트라면 설정 파일부터 패키지까지 전부 달라진다. PostCSS 설정도 바뀌었다. 처음 보면 당황스럽지만 전환 자체는 생각보다 빠르다. 자동 CLI 한 번으로 80%는 처리된다.

이 글에서는 설치부터 @theme 문법, 바뀐 클래스명, 커스텀 플러그인 처리까지 정리했다. v4 전환을 고민 중이라면 처음부터 읽으면 된다. 신규 프로젝트라면 "언제 올려야 하나" 섹션으로 바로 가도 된다.

빠르게 보기

tailwind.config.js → CSS @theme 블록으로 전환
Rust 기반 Oxide 컴파일러 — 전체 빌드 최대 5배, 증분 빌드 최대 100배 향상
자동 content 감지 — content 배열 설정 불필요
CSS 변수로 커스텀 토큰 직접 정의 (JS 없이)
npx @tailwindcss/upgrade로 자동 마이그레이션 가능

설정 파일이 CSS로 들어왔다
@theme 문법 파고들기
Oxide 컴파일러가 속도를 바꿨다
v3에서 v4로 전환하는 순서
Next.js + PostCSS 설정 방법
바뀐 클래스명 체크리스트
커스텀 플러그인 대응
v3 vs v4 한눈에 비교
언제 올려야 하나
자주 묻는 질문

설정 파일이 CSS로 들어왔다

v3까지는 JS 파일로 설정했다. v4는 CSS 파일 하나로 끝난다. @import "tailwindcss" 한 줄로 시작하고, @theme 블록에 커스텀 값을 넣으면 된다. JS 의존성이 하나 줄었다.

기존에 @tailwind base;, @tailwind components;, @tailwind utilities; 세 줄을 썼다면 전부 지운다. @import "tailwindcss" 한 줄로 대체된다. 지시어가 단순해졌다.

@theme은 CSS 변수로 동작한다. 디자인 토큰을 JS 없이 CSS 안에서 관리하는 구조다. 브라우저 DevTools에서 변수 값을 바로 확인할 수 있다. 설정값이 빌드 결과물 밖으로 노출된다는 뜻이다.

/* v4: CSS 파일에서 직접 설정 */

@import "tailwindcss";

@theme {

  --font-display: "Pretendard Variable", sans-serif;

  --color-brand: oklch(0.70 0.18 250);

  --color-brand-dark: oklch(0.55 0.20 250);

  --spacing-gutter: 2rem;

  --breakpoint-3xl: 1920px;

  /* 전체 네임스페이스 초기화 후 재정의 */

  --color-*: initial;

  --color-gray-50: #f9fafb;

}

@theme 문법 파고들기

@theme 블록 안의 변수는 네이밍 규칙이 있다. --color-{name}, --font-{name}, --spacing-{name} 형태다. Tailwind가 이 네임스페이스를 읽어 유틸리티 클래스를 자동 생성한다. --color-brand를 정의하면 text-brand, bg-brand 클래스가 바로 생긴다.

색상 정의에 oklch() 형식을 권장한다. oklch는 HSL의 후계자다 — 화면에서 일관된 밝기로 보이는 색 공간이다. oklch(0.70 0.18 250)처럼 밝기·채도·색상각으로 정의한다. 구형 브라우저 폴백은 자동으로 처리된다.

--color-*: initial 문법으로 특정 네임스페이스 전체를 초기화할 수 있다. 기본 색상 팔레트를 지우고 디자인 시스템 토큰만 남기고 싶을 때 쓴다. 불필요한 유틸리티가 빌드에 포함되는 걸 막는다.

@theme 변수 네임스페이스 목록
--color-* → text-*, bg-*, border-* 등 색상 유틸리티
--font-* → font-{name} 폰트 패밀리
--text-* → text-{size} 폰트 크기
--spacing-* → p-*, m-*, gap-* 등 간격
--breakpoint-* → sm:, md:, lg: 등 반응형 브레이크포인트
--radius-* → rounded-{name} 모서리 반경

Oxide 컴파일러가 속도를 바꿨다

v4가 빨라진 핵심은 Rust로 만든 Oxide 컴파일러다. Oxide는 기존 Node.js 파이프라인을 Rust로 교체한 것이다. 공식 벤치마크 기준 전체 빌드 최대 5배, 증분 빌드는 최대 100배 빠르다.

content 경로 감지도 자동이다. v3에서는 content: ['./src/**/*.tsx']처럼 직접 적어야 했다. v4는 프로젝트 구조를 스캔해서 알아서 찾는다. 설정 항목이 줄었다.

Oxide는 별도 설치 없이 tailwindcss v4 패키지에 포함되어 있다. 설치하면 자동으로 활성화된다. Vite나 PostCSS 플러그인을 통해 기존 파이프라인에 그대로 연결된다. 마이그레이션해도 워크플로우가 크게 바뀌지 않는다.

v3에서 v4로 전환하는 순서

공식 업그레이드 CLI가 있다. npx @tailwindcss/upgrade를 실행하면 설정 파일 변환과 클래스 리네임을 자동으로 처리한다. 커스텀 플러그인이 없는 프로젝트라면 이 한 줄로 끝난다.

PostCSS 사용 중이라면 @tailwindcss/postcss로 교체한다. Vite 프로젝트는 @tailwindcss/vite 플러그인을 쓰면 된다. Next.js는 @tailwindcss/postcss 경로로 처리된다.

# 1단계: 자동 마이그레이션 CLI 실행

npx @tailwindcss/upgrade@next

# 2단계: 패키지 교체 (PostCSS 기준)

npm install tailwindcss@next @tailwindcss/postcss

# Vite 프로젝트라면

npm install tailwindcss@next @tailwindcss/vite

자동 CLI 실행 후에는 반드시 diff를 확인한다. 동적으로 조합하는 클래스명(bg-${color}-500 패턴)은 자동 변환 대상이 아니다. CSS-in-JS 라이브러리와 함께 쓰는 프로젝트도 수동 검증이 필요하다.

Next.js + PostCSS 설정 방법

Next.js 기준 수동 설정 순서는 세 단계다. 패키지 교체, PostCSS 설정 변경, CSS 파일 수정이다. 자동 CLI가 이 세 단계를 한 번에 처리하지만, 직접 하면 구조를 이해하는 데 도움이 된다.

// postcss.config.js (v4)

export default {

  plugins: {

    '@tailwindcss/postcss': {}

  }

};

/* globals.css (v4) */

/* 기존 @tailwind 지시어 세 줄 → 한 줄로 */

@import "tailwindcss";

@theme {

  --font-sans: "Pretendard Variable", sans-serif;

}

tailwind.config.js는 삭제해도 되고 그냥 둬도 된다. v4에서는 읽지 않는다. 팀 협업 중이라면 혼선을 줄이기 위해 삭제하는 게 낫다.

Next.js v4 전환 체크리스트

npm install tailwindcss@next @tailwindcss/postcss 실행
postcss.config.js에서 tailwindcss → @tailwindcss/postcss 교체
globals.css 상단 @tailwind 세 줄 → @import "tailwindcss"로 교체
tailwind.config.js 커스텀 값 → @theme 블록으로 이전
빌드 후 스타일 깨진 곳 확인 (특히 동적 클래스명)

바뀐 클래스명 체크리스트

클래스명이 일부 바뀌었다. 자동 CLI가 대부분을 처리하지만, CSS-in-JS나 동적 클래스명 조합 패턴은 수동 확인이 필요하다. 아래 목록은 실제로 자주 쓰는 것 위주로 정리했다.

v3 방식	v4 방식	비고
`@tailwind base/components/utilities`	`@import "tailwindcss"`	CSS 파일 최상단 한 줄
`outline-none`	`outline-hidden`	포커스 링 숨김 목적일 때
`plugins: [require('...')]`	`@plugin "..."`	CSS에서 선언
`theme.extend.colors.brand: '...'`	`--color-brand: ...`	@theme 블록 안에
`content: ['./src/*/.tsx']`	설정 불필요	자동 감지
`theme()` CSS 함수	`var(--color-brand)`	CSS 변수 직접 참조

outline-none은 특히 조심해야 한다. v3에서는 outline: 2px solid transparent로 동작했다. v4에서는 outline: none으로 바뀌었다. 버튼이나 input에서 포커스 링을 숨기려고 쓰던 코드는 outline-hidden으로 교체해야 한다. 접근성 테스트에서 걸릴 수 있는 부분이다.

커스텀 플러그인 대응

기존 플러그인은 @plugin 지시어로 CSS에서 선언한다. tailwind.config.js의 plugins 배열이 사라지면서 방식이 바뀌었다. 공식 플러그인은 패키지 이름만 전달하면 된다.

@import "tailwindcss";

/* 공식 플러그인 */

@plugin "@tailwindcss/typography";

@plugin "@tailwindcss/forms";

/* 직접 만든 플러그인 */

@plugin "./plugins/my-plugin.js";

@theme {

  --color-brand: oklch(0.70 0.18 250);

}

직접 만든 JS 플러그인은 파일 경로를 @plugin에 전달하면 동작한다. addUtilities, addComponents 같은 기존 API는 대부분 유지됐다. 단, v4 플러그인 API 일부가 달라졌기 때문에 마이그레이션 후 동작 확인이 필요하다. 공식 문서의 플러그인 마이그레이션 가이드를 확인하면 된다.

v3 vs v4 한눈에 비교

항목	v3	v4
설정 방식	tailwind.config.js	CSS @theme 블록
컴파일러	Node.js	Rust (Oxide)
content 감지	수동 경로 설정	자동 감지
커스텀 토큰	theme.extend (JS)	CSS 변수 (@theme)
빌드 속도	기준	최대 5배 향상
증분 빌드	기준	최대 100배 향상
플러그인 선언	plugins 배열 (JS)	@plugin 지시어 (CSS)
자동 마이그레이션	없음	@tailwindcss/upgrade CLI

상황	권장 방향	이유
신규 프로젝트	v4 시작	단순하고 빠름
빌드 속도가 병목인 프로젝트	v4 전환	증분 빌드 최대 100배
복잡한 커스텀 JS 플러그인	v3 유지 후 검토	API 변경 수동 확인 필요
Vite 기반 프로젝트	v4 전환 적합	공식 Vite 플러그인 지원
CSS-in-JS 혼용	전환 전 수동 테스트	동적 클래스명 자동 감지 안 됨

언제 올려야 하나

신규 프로젝트라면 v4로 시작하는 게 맞다. v3보다 단순하고 빠르다. JS 설정 파일 없이 CSS만으로 디자인 토큰을 관리할 수 있다는 게 장기적으로 가장 큰 이점이다. 팀원이 JS를 잘 모르는 디자이너도 CSS 변수를 직접 수정할 수 있다.

기존 프로젝트는 상황에 따라 다르다. 빌드 속도가 체감될 만큼 느리거나, tailwind.config.js가 점점 복잡해지고 있다면 지금 올릴 이유가 충분하다. 반대로 복잡한 커스텀 플러그인이 많거나 레거시 PostCSS 파이프라인에 깊게 묶여 있으면 천천히 가도 된다.

v3는 계속 지원된다. v4 전환이 급하지 않다. 다만 새로운 기능과 성능 개선은 v4에서만 이뤄진다. 지금 당장은 아니어도, 연내 전환을 계획에 넣는 게 현실적이다.

v4 전환을 미뤄야 하는 신호