🔄 Миграция Tailwind v3 → v4

Что переехало, что переименовано, план перехода

Зачем этот справочник

Большая часть статей, ответов на форумах и готовых тем написана для Tailwind v3. Их инструкции в v4 не работают или работают иначе. Здесь собраны все различия, с которыми вы столкнётесь.

Как быстро определить версию: есть tailwind.config.js и три директивы @tailwind — это v3. Один @import "tailwindcss" и блок @theme — это v4.

Установка и подключение

Что	v3	v4
Подключение в CSS	`@tailwind base/components/utilities`	`@import "tailwindcss";`
Инициализация	`npx tailwindcss init -p`	не нужна
Плагин Vite	через PostCSS	`@tailwindcss/vite`
Плагин PostCSS	`tailwindcss`	`@tailwindcss/postcss`
CLI	`tailwindcss`	`@tailwindcss/cli`
Автопрефиксы	`autoprefixer`	встроены
Файлы для сканирования	поле `content`	автоопределение + `@source`

Тема

❌ v3

module.exports = {
  darkMode: ["class"],
  theme: {
    extend: {
      colors: { brand: { 500: "#4f46e5" } },
      spacing: { huge: "7.5rem" },
      screens: { tablet: "960px" },
      borderRadius: { xl: "1rem" },
    },
  },
  plugins: [require("tailwindcss-animate")],
}

✅ v4

@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --color-brand-500: oklch(0.51 0.26 277);
  --spacing-huge: 7.5rem;
  --breakpoint-tablet: 60rem;
  --radius-xl: 1rem;
}

Настройка	v3	v4
Цвет	`theme.extend.colors`	`--color-*`
Отступ	`theme.spacing`	`--spacing-*`
Брейкпоинт	`theme.screens`	`--breakpoint-*`
Шрифт	`theme.fontFamily`	`--font-*`
Радиус	`theme.borderRadius`	`--radius-*`
Тёмная тема	`darkMode: ["class"]`	`@custom-variant dark (…)`
Своя утилита	плагин на JS	`@utility`
Свой вариант	`addVariant`	`@custom-variant`
Сброс палитры	переопределение объекта	`--color-*: initial;`

Старый конфиг можно временно подключить: @config "./tailwind.config.js";

Переименованные утилиты

Самая коварная группа: классы существуют в обеих версиях, но означают разное. Ошибок сборки не будет — просто изменится внешний вид.

v3	v4	Комментарий
`shadow-sm`	`shadow-xs`	шкала теней сдвинулась
`shadow`	`shadow-sm`	безымянный вариант убран
`rounded-sm`	`rounded-xs`	то же для радиусов
`rounded`	`rounded-sm`	—
`blur`	`blur-sm`	то же для фильтров
`ring` (3px)	`ring` (1px)	для прежнего вида — `ring-3`
`outline-none`	`outline-hidden`	сохраняет контур в режиме высокой контрастности
`bg-gradient-to-r`	`bg-linear-to-r`	появились `bg-radial`, `bg-conic`
`bg-opacity-50`	`bg-black/50`	прозрачность модификатором
`flex-shrink-0`	`shrink-0`	короче
`flex-grow`	`grow`	короче
`overflow-ellipsis`	`text-ellipsis`	—
`decoration-slice`	`box-decoration-slice`	—

Изменения поведения

Что	Было	Стало
Цвет границы по умолчанию	серый	`currentColor`
Цвет палитры	RGB	OKLCH — оттенки выглядят чуть иначе
Единицы брейкпоинтов	px	rem
Container queries	плагин	в ядре
Трансформации	нужен класс `transform`	работают сразу
Слои CSS	эмуляция	настоящие `@layer`
Произвольные значения	`w-[var(--x)]`	ещё и `w-(--x)`

План миграции

Обновить зависимости: tailwindcss, добавить @tailwindcss/vite или @tailwindcss/postcss.
Заменить три директивы на @import "tailwindcss";
Перенести тему из конфига в @theme (или временно подключить конфиг через @config).
Настроить тёмную тему через @custom-variant.
Пройти по таблице переименований — особенно тени, радиусы и ring.
Проверить внешний вид: цвета в OKLCH выглядят немного иначе.
Удалить autoprefixer и плагины, чьи возможности вошли в ядро.

⚠️ Проверить по документации: у Tailwind есть официальный инструмент обновления (npx @tailwindcss/upgrade) — уточните его актуальную форму вызова в разделе Upgrade guide.