업그레이드 가이드

Tailwind CSS v3.0은 완전히 새로운 내부 엔진을 도입한 주요 업데이트이며, 이로 인해 일부 호환성이 깨지는 변경 사항이 포함되어 있습니다.

우리는 안정성을 매우 중요하게 여기며, 이러한 변경 사항이 최대한 고통스럽지 않도록 노력했습니다. 대부분의 프로젝트에서 Tailwind CSS v3.0으로 업그레이드하는 데 30분 이내의 시간이 소요될 것입니다.

Tailwind CSS v3.0의 새로운 기능에 대해 더 알아보려면, 우리 블로그의 Tailwind CSS v3.0 발표를 확인해 보세요.

패키지 업그레이드

Tailwind, PostCSS, autoprefixer를 npm을 사용해 최신 버전으로 업데이트하세요:

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

Tailwind CSS v3.0은 PostCSS 8을 필요로 하며, PostCSS 7을 더 이상 지원하지 않습니다. PostCSS 8로 업그레이드할 수 없는 경우, Tailwind를 PostCSS 플러그인으로 설치하는 대신 Tailwind CLI를 사용하는 것을 권장합니다.

커스텀 CSS에서 중첩(nesting)을 사용하고 있다면 (PostCSS 중첩 플러그인과 함께), Tailwind CSS v3.0과의 호환성을 보장하기 위해 PostCSS 설정에서 tailwindcss/nesting 플러그인을 구성해야 합니다.

공식 플러그인

모든 퍼스트파티 플러그인이 v3.0과 호환되도록 업데이트되었습니다.

플러그인을 사용 중이라면, 버전 충돌 오류를 방지하기 위해 모든 플러그인을 동시에 최신 버전으로 업데이트해야 합니다.

npm install -D tailwindcss@latest \
  @tailwindcss/typography@latest \
  @tailwindcss/forms@latest \
  @tailwindcss/aspect-ratio@latest \
  @tailwindcss/line-clamp@latest \
  postcss@latest \
  autoprefixer@latest

Play CDN

Tailwind CSS v3.0부터, 이전에 제공하던 CSS 기반 CDN 빌드는 새로운 Play CDN으로 대체되었습니다. 이 새로운 엔진은 브라우저에서 바로 사용할 수 있으며, 별도의 빌드 과정 없이도 모든 기능을 제공합니다.

이를 사용해 보려면, <head> 태그 안에 아래 <script> 태그를 추가하세요:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <script src="https://cdn.tailwindcss.com"></script>
  </head>
  <body>
    <!-- -->
  </body>
</html>

Play CDN은 개발 목적으로만 설계되었습니다. 프로덕션 환경에서는 직접 정적 CSS 빌드를 컴파일하는 것이 훨씬 더 나은 선택입니다.

JIT 엔진으로 마이그레이션하기

우리가 3월에 발표한 새로운 JIT(Just-in-Time) 엔진이 Tailwind CSS v3.0에서 기존 엔진을 대체했습니다.

이 새로운 엔진은 프로젝트에 필요한 스타일을 필요할 때마다 생성하며, Tailwind 설정에 따라 프로젝트에 약간의 변경이 필요할 수 있습니다.

Tailwind CSS v2.x에서 이미 mode: 'jit'를 사용하고 있었다면, v3.0에서는 설정에서 이를 안전하게 제거할 수 있습니다:

tailwind.config.js

module.exports = {
  mode: 'jit',
  // ...
}

콘텐츠 소스 설정

Tailwind는 더 이상 내부적으로 PurgeCSS를 사용하지 않기 때문에, purge 옵션을 content로 이름을 변경했습니다. 이는 해당 옵션의 목적을 더 잘 반영하기 위함입니다:

tailwind.config.js

module.exports = {
  purge: [
  content: [
    // 콘텐츠 경로 예시...
    './public/**/*.html',
    './src/**/*.{js,jsx,ts,tsx,vue}',
  ],
  theme: {
    // ...
  }
  // ...
}

만약 프로젝트에서 purge 옵션을 사용하지 않았다면, 이제 템플릿 경로를 설정하는 것이 중요합니다. 그렇지 않으면 컴파일된 CSS가 비어 있을 수 있습니다.

PurgeCSS를 더 이상 내부적으로 사용하지 않기 때문에, 몇 가지 고급 purge 옵션이 변경되었습니다. 고급 옵션에 대한 자세한 내용은 새로운 콘텐츠 설정 문서를 참고하세요.

다크 모드 설정 제거

이제 다크 모드 기능은 기본적으로 media 전략을 사용해 활성화됩니다. 따라서 class 전략을 사용하지 않는 한, tailwind.config.js 파일에서 이 설정을 완전히 제거할 수 있습니다.

tailwind.config.js

module.exports = {
  darkMode: 'media',
  // ...
}

현재 이 설정이 false로 되어 있다면, 이 설정을 안전하게 제거할 수도 있습니다.

tailwind.config.js

module.exports = {
  darkMode: false,
  // ...
}

variant 설정 제거

Tailwind CSS v3.0부터는 모든 variant가 기본적으로 모든 유틸리티에 자동으로 적용됩니다. 따라서 tailwind.config.js 파일에서 variants 섹션을 제거할 수 있습니다:

tailwind.config.js

module.exports = {
  // ...
  variants: {
    extend: {
      padding: ['hover'],
    }
  },
}

@variants를 @layer로 대체하기

이제 모든 변형(variants)이 기본적으로 활성화되었기 때문에, 커스텀 CSS에 @variants나 @responsive 지시자를 사용해 명시적으로 활성화할 필요가 없습니다.

대신, @layer 지시자를 사용해 적절한 “레이어”에 커스텀 CSS를 추가하세요:

 @variants hover, focus {
 @layer utilities {
   .content-auto {
     content-visibility: auto;
   }
 }

Tailwind의 레이어 중 하나에 추가된 모든 커스텀 CSS는 자동으로 변형을 지원합니다.

더 많은 정보는 CSS와 @layer를 사용해 커스텀 스타일 추가하기 문서를 참고하세요.

자동 변환 및 필터

Tailwind CSS v3.0에서는 scale-50이나 brightness-75와 같은 변환 및 필터 유틸리티가 transform, filter, backdrop-filter 클래스를 추가하지 않아도 자동으로 적용됩니다.

<div class="transform scale-50 filter grayscale backdrop-filter backdrop-blur-sm">
<div class="scale-50 grayscale backdrop-blur-sm">

HTML에 이 클래스들을 남겨두는 데 문제는 없지만, 안전하게 제거할 수 있습니다. 단, 한 가지 예외가 있습니다. transform을 사용해 새로운 z-index 기반 레이어링을 생성하는 경우, 이 클래스를 남겨두는 것이 좋습니다. 그렇지 않으면 z-order 문제가 발생할 수 있습니다. 또는 relative나 isolate로 대체하여 새로운 z-index 기반 레이어링을 강제할 수도 있습니다.

새로운 투명도 조정 문법

새로운 엔진에서는 색상 유틸리티의 투명도를 변경하기 위한 새로운 문법을 도입했습니다. 이제 bg-opacity-*와 같은 유틸리티 대신 새로운 문법을 사용하는 것을 권장합니다:

<div class="bg-black bg-opacity-25">
<div class="bg-black/25">

기존 방식은 여전히 대부분의 경우에서 동작하지만, 기본 border 클래스와 함께 border-opacity-* 유틸리티를 사용할 때는 예외입니다. v3에서는 테두리 색상을 명시적으로 지정해야 합니다:

<div class="border border-opacity-25">
<div class="border border-gray-200/25">

다른 모든 상황에서는 동일하게 동작하므로, 이 변경 사항 외에는 프로젝트가 이전과 동일하게 작동합니다. 하지만 앞으로는 새로운 문법을 사용하는 것을 권장하며, v4에서는 기본적으로 border-opacity-* 및 bg-opacity-*와 같은 유틸리티를 비활성화할 계획입니다. 필요하다면 여전히 이를 활성화할 수 있습니다.

이 새로운 문법은 모든 색상 유틸리티에 적용되며, 이전에는 투명도를 조정할 방법이 없었던 from-red-500/75와 같은 유틸리티에도 사용할 수 있습니다.

색상 팔레트 변경 사항

Tailwind CSS v3.0부터는 기본적으로 확장된 색상 팔레트의 모든 색상이 포함됩니다. 이전에는 비활성화되어 있던 cyan, rose, fuchsia, lime 색상과 gray의 다섯 가지 변형도 모두 기본으로 제공됩니다.

색상 별칭 제거

v2.0에서는 기본 색상 중 일부가 확장 색상의 별칭으로 사용되었습니다:

v2 기본	v2 확장
`green`	`emerald`
`yellow`	`amber`
`purple`	`violet`

v3.0에서는 이 색상들이 기본적으로 확장 이름을 사용하도록 변경되었습니다. 따라서 이전에 bg-green-500이었던 것은 이제 bg-emerald-500이 되었고, bg-green-500은 이제 확장 팔레트의 녹색을 참조합니다.

프로젝트에서 이 색상들을 사용 중이라면, tailwind.config.js 파일에서 이전 이름으로 별칭을 다시 설정하는 것이 가장 간단한 업그레이드 방법입니다:

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        green: colors.emerald,
        yellow: colors.amber,
        purple: colors.violet,
      }
    },
  },
  // ...
}

이미 커스텀 색상 팔레트를 사용 중이라면, 이 변경 사항은 전혀 영향을 미치지 않습니다.

회색 스케일 이름 변경

기본적으로 모든 확장 색상을 활성화하면서, 다양한 회색 음영에 더 실용적이고 동시에 사용하기에 덜 어색한 짧은 단일 단어 이름을 부여했습니다.

v2 기본	v2 확장	v3 통합
N/A	`blueGray`	`slate`
`gray`	`coolGray`	`gray`
N/A	`gray`	`zinc`
N/A	`trueGray`	`neutral`
N/A	`warmGray`	`stone`

확장된 회색을 참조하고 있었다면, 새로운 이름으로 업데이트해야 합니다. 예를 들어:

tailwind.config.js

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extend: {
      colors: {
        gray: colors.trueGray,
        gray: colors.neutral,
      }
    },
  },
  // ...
}

확장된 색상 팔레트에서 회색을 참조하지 않았다면, 이 변경 사항은 전혀 영향을 미치지 않습니다.

클래스명 변경 사항

Tailwind CSS v3.0에서는 이름 충돌을 방지하고, 개발자 경험을 개선하며, 새로운 기능을 지원하기 위해 일부 클래스명이 변경되었습니다.

가능한 경우 기존 이름도 유지했기 때문에 대부분의 변경 사항은 비호환적이지 않습니다. 하지만 새로운 클래스명으로 업데이트하는 것을 권장합니다.

overflow-clip/ellipsis

브라우저 개발자들이 진짜 overflow: clip 속성을 추가해 버렸기 때문에, text-overflow: clip을 위해 overflow-clip을 사용하는 것은 이제 정말 나쁜 아이디어가 되었습니다.

이름 충돌을 피하기 위해 overflow-clip을 text-clip으로, overflow-ellipsis를 text-ellipsis로 이름을 변경했습니다:

<div class="overflow-clip overflow-ellipsis">
<div class="text-clip text-ellipsis">

text-clip을 사용하는 경우가 매우 드물고, 단순히 완성도를 위해 포함된 것이기 때문에 이 변경이 누군가에게 영향을 미칠 가능성은 거의 없습니다.

flex-grow/shrink

flex-grow-*와 flex-shrink-*에 대한 별칭으로 grow-*와 shrink-*를 추가했습니다:

<div class="flex-grow-0 flex-shrink">
<div class="grow-0 shrink">

기존 클래스 이름도 계속 작동하지만, 새로운 이름으로 업데이트하는 것을 권장합니다.

outline-black/white

최근 브라우저들이 아웃라인을 렌더링할 때 테두리 반경(border radius)을 존중하기 시작하면서, outline-style, outline-color, outline-width, 그리고 outline-offset 속성을 위한 별도의 유틸리티를 추가했습니다.

이제 outline-white와 outline-black은 아웃라인의 _색상_만 설정하며, v2에서는 색상, 너비, 스타일, 오프셋을 모두 설정했던 것과 달라졌습니다.

프로젝트에서 outline-white나 outline-black을 사용 중이라면, 다음 커스텀 CSS를 추가하여 이전 스타일을 복원할 수 있습니다:

@layer utilities {
  .outline-black {
    outline: 2px dotted black;
    outline-offset: 2px;
  }

  .outline-white {
    outline: 2px dotted white;
    outline-offset: 2px;
  }
}

또는, CSS에서 해당 클래스를 사용하는 부분을 다음과 같이 업데이트할 수도 있습니다:

<div class="outline-black">
<div class="outline-black outline-2 outline-dotted outline-offset-2">

<div class="outline-white">
<div class="outline-white outline-2 outline-dotted outline-offset-2">

decoration-clone/slice

새로운 text-decoration 유틸리티들이 decoration- 네임스페이스를 사용하면서 혼동을 피하기 위해 box-decoration-clone과 box-decoration-slice를 decoration-clone 및 decoration-slice의 별칭으로 추가했습니다:

<div class="decoration-clone"></div>
<div class="box-decoration-clone"></div>

<div class="decoration-slice"></div>
<div class="box-decoration-slice"></div>

기존 클래스 이름도 계속 작동하지만, 새로운 이름으로 업데이트하는 것을 권장합니다.

기타 사소한 변경 사항

Tailwind CSS v3.0에는 많은 사람들에게 영향을 미치지 않을 가능성이 높지만, 여기에 기록된 몇 가지 작은 주요 변경 사항이 필요합니다.

구분자로 대시를 사용할 수 없음

v3.0에서는 파싱 모호성을 유발하기 때문에 대시(-) 문자를 커스텀 구분자로 사용할 수 없습니다.

대신 _와 같은 다른 문자로 변경해야 합니다:

tailwind.config.js

module.exports = {
  // ...
  separator: '-',
  separator: '_',
}

접두사는 함수가 될 수 없음

Tailwind CSS v3.0 이전에는 클래스 접두사를 함수로 정의할 수 있었습니다:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  prefix(selector) {
    // ...
  },
}

하지만 새로운 엔진에서는 이 기능을 지원할 수 없어 제거되었습니다.

대신, Tailwind가 생성하는 모든 클래스에 동일하게 적용되는 정적 접두사를 사용하세요:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  prefix: 'tw-',
}

파일 수정자 순서 변경

v3.0.0-alpha.2에서 file 수정자가 도입된 이후로 아주 사소한 변경이 있었습니다. 만약 hover나 focus와 같은 다른 수정자와 함께 사용하고 있었다면, 수정자 순서를 뒤집어야 합니다:

<input class="file:hover:bg-blue-600 ...">
<input class="hover:file:bg-blue-600 ...">

더 자세한 내용은 스택된 수정자 순서 문서에서 확인할 수 있습니다.

채우기와 스트로크에 색상 팔레트 사용

기본적으로 fill-*와 stroke-* 유틸리티는 이제 theme.colors 키를 반영합니다. 색상 팔레트를 커스텀하지 않았다면 이 변경은 문제가 되지 않지만, 커스텀 색상 팔레트를 사용 중이라면 current가 포함되어 있지 않을 경우 fill-current와 stroke-current 클래스가 작동하지 않을 수 있습니다.

이 문제를 해결하려면 커스텀 색상 팔레트에 current를 추가하세요:

tailwind.config.js

module.exports = {
  // ...
  theme: {
    colors: {
      current: 'currentColor',
      // ...
    }
  }
}

음수 값 제거

-mx-4와 같은 유틸리티에서 음수 접두사는 이제 테마에 의해 결정되는 것이 아니라 Tailwind의 퍼스트클래스 기능으로 제공됩니다. 따라서 음수 값을 지원하는 모든 유틸리티 앞에 -를 추가하면 바로 작동합니다.

기본 테마에서 음수 값이 제거되었기 때문에, theme()을 사용하여 음수 값을 참조하던 경우 CSS 컴파일 시 오류가 발생할 수 있습니다.

영향을 받는 코드를 업데이트하려면 calc() 함수를 사용하세요:

.my-class {
  top: theme('top.-4')
  top: calc(theme('top.4') * -1)
}

기본 레이어는 반드시 포함되어야 함

Tailwind CSS v3.0에서는 @tailwind base 지시문이 반드시 포함되어야 변환(transforms), 필터(filters), 그림자(shadows)와 같은 유틸리티가 정상적으로 작동합니다.

이전에 이 지시문을 포함하지 않아 Tailwind의 기본 스타일을 비활성화했다면, 이제 다시 추가하고 corePlugins 설정에서 preflight를 비활성화해야 합니다:

main.css

 @tailwind base;
 @tailwind components;
 @tailwind utilities;

tailwind.config.js

module.exports = {
  // ...
  corePlugins: {
    preflight: false,
  },
}

이렇게 하면 Tailwind의 전역 기본 스타일을 비활성화하면서도, 자체 기본 스타일을 추가해야 정상적으로 작동하는 유틸리티에는 영향을 미치지 않습니다.

Screens 레이어 이름이 변경되었습니다

@tailwind screens 레이어가 @tailwind variants로 이름이 변경되었습니다:

main.css

 /* ... */
 @tailwind screens;
 @tailwind variants;

이 변경으로 인해 영향을 받을 가능성은 책상에서 일하다 상어에게 공격당할 가능성보다도 낮을 것입니다.

On this page