Миграция на Tailwind CSS v4: полный гайд с примерами и решением частых проблем

Обновились до Tailwind v4 и всё сломалось? Или только планируете переход и не хотите наступать на чужие грабли? В этой статье - пошаговый разбор миграции с Tailwind CSS v3 на v4: что изменилось, почему, какие ошибки встречаются чаще всего и как их исправить.

Подойдёт для разработчиков, которые уже работали с Tailwind и хотят перейти на новую версию без боли.

Что такое Tailwind CSS v4 и зачем на него переходить

Tailwind CSS v4 - это крупный релиз фреймворка, вышедший в 2025 году. Он переписан на Rust (через Oxide - новый движок), что даёт значительный прирост скорости сборки: в среднем в 5–10 раз быстрее по сравнению с v3.

Ключевые изменения версии:

• Конфигурация переехала из tailwind.config.js в CSS-файл (@theme директива)

• Удалён устаревший JIT-режим - теперь он единственный и встроенный

• Новый синтаксис для кастомных значений и тем

• Изменения в именовании утилит (часть классов переименована)

• Нативная поддержка CSS-переменных без лишних обёрток

• Официальный Vite-плагин вместо PostCSS-зависимостей

Если ваш проект на v3 работает стабильно и не требует обновлений - торопиться не нужно. Но для новых проектов v4 уже является стандартом де-факто.

Почему переход с v3 на v4 может быть болезненным

Tailwind v4 - это breaking change практически по всем фронтам. Авторы не старались сохранить обратную совместимость ради ускорения и упрощения архитектуры.

Основные причины трудностей при миграции:

1. Конфиг полностью переехал. Если у вас большой tailwind.config.js с кастомными цветами, шрифтами, брейкпоинтами и плагинами - всё это нужно переписывать в CSS.

2. Переименованы утилиты. Например, shadow-sm теперь называется иначе, blur без размера был удалён, изменились дефолтные значения теней.

3. Плагины не совместимы. Большинство сторонних плагинов для v3 не работают с v4 без обновления со стороны авторов.

4. PostCSS-интеграция изменилась. Tailwind v4 предпочитает использоваться как Vite-плагин, а не через PostCSS напрямую.

Частые ошибки при миграции на Tailwind v4

1. Оставить tailwind.config.js без изменений

Tailwind v4 его не читает. Никакой ошибки не будет - просто кастомизации не применятся. Люди часто теряют часы, пытаясь понять, почему их цвета не работают.

2. Использовать старый PostCSS-конфиг

// postcss.config.js - старый способ (v3)
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

В v4 с Vite это не нужно. Если оставить - возможны конфликты или двойная обработка.

3. Неправильная настройка @import

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

Использование старого синтаксиса @tailwind в v4 просто не даст нужного результата.

4. Игнорирование переименованных утилит

Список изменений достаточно длинный. Самые частые:

• flex-shrink → shrink

• flex-grow → grow

• overflow-ellipsis → text-ellipsis

• decoration-slice → box-decoration-slice

Если после миграции верстка «поехала» - первым делом проверяйте именно эти классы.

5. Запуск официального codemoda без предварительного бэкапа

@tailwindcss/upgrade - полезный инструмент, но он меняет файлы на месте. Без git-коммита или резервной копии можно потерять ручные правки.

Пошаговая миграция с Tailwind v3 на v4

Шаг 1. Обновите зависимости

npm install tailwindcss@next @tailwindcss/vite

Если используете PostCSS:

npm install tailwindcss@next @tailwindcss/postcss

Шаг 2. Запустите официальный инструмент апгрейда

npx @tailwindcss/upgrade

Он автоматически:

• обновит импорты в CSS

• переименует устаревшие утилиты

• попытается перенести tailwind.config.js в CSS-формат

Проверьте результат вручную - автоматика справляется не со всем.

Шаг 3. Перенесите конфиг в CSS

Было (v3, tailwind.config.js):

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#6366f1',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
}

Стало (v4, в CSS-файле):

@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
  --font-family-sans: 'Inter', sans-serif;
}

Шаг 4. Обновите конфиг Vite

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

Шаг 5. Обновите главный CSS-файл

/* src/index.css */
@import "tailwindcss";

/* Ваша кастомная тема */
@theme {
  --color-primary: #3b82f6;
  --spacing-18: 4.5rem;
}

Шаг 6. Проверьте и исправьте переименованные классы

Пройдитесь по компонентам и шаблонам. Особое внимание:

• утилиты с flex-

• тени (shadow-*)

• кольца (ring-*)

• псевдоэлементы

Шаг 7. Обновите или замените несовместимые плагины

Проверьте репозитории плагинов, которые вы используете (например @tailwindcss/typography, @tailwindcss/forms). Для v4 вышли обновлённые версии большинства официальных плагинов.

Практические примеры

Кастомные CSS-переменные и тема

@theme {
  /* Цвета */
  --color-accent: oklch(70% 0.2 240);
  --color-surface: #f8fafc;

  /* Шрифты */
  --font-heading: 'Manrope', sans-serif;

  /* Брейкпоинты */
  --breakpoint-xs: 480px;
}

После этого вы можете использовать text-accent, bg-surface, font-heading, xs:... прямо в HTML.

Динамические значения

<!-- v3 -->
<div class="w-[340px] mt-[22px]">

<!-- v4 - синтаксис не изменился, но теперь нативно поддерживаются CSS-переменные -->
<div class="w-(--sidebar-width) mt-4">

Темизация через CSS-переменные

@theme {
  --color-bg: #ffffff;
  --color-text: #0f172a;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #0f172a;
    --color-text: #f8fafc;
  }
}

Часто задаваемые вопросы (FAQ)

Можно ли использовать Tailwind v4 без Vite? Да. Поддерживается PostCSS-плагин (@tailwindcss/postcss) и CLI. Но Vite-интеграция рекомендована как основная.

Tailwind v4 совместим с React / Vue / Svelte? Да, со всеми. Tailwind работает на уровне CSS, не зависит от фреймворка. Нужно лишь правильно настроить сборщик.

Что делать, если плагин для v3 не поддерживает v4? Проверьте GitHub плагина - возможно, уже вышла ветка с поддержкой v4. Если нет - напишите issue или найдите альтернативу. В крайнем случае нужную функциональность можно воспроизвести через @theme и кастомные утилиты.

Нужно ли удалять tailwind.config.js после миграции? Да. Tailwind v4 его не читает, и его присутствие только вводит в заблуждение. Оставьте в виде архива, если нужна справка по старым значениям.

Работает ли @apply в v4? Да, директива @apply сохранена. Но разработчики рекомендуют использовать её осторожно - она снижает преимущества нового движка.

Изменился ли синтаксис content для сканирования файлов? В v4 автодетект работает по умолчанию - Tailwind сам находит файлы проекта. Вручную указывать пути нужно только в нестандартных случаях через @source.

Насколько быстрее v4 по сравнению с v3? На больших проектах инкрементальная сборка ускоряется в 5–10 раз. Полная первоначальная сборка - примерно в 2–3 раза.

Поддерживается ли TypeScript в конфигурации v4? Конфиг теперь в CSS, TypeScript там не нужен. Для тайпингов в редакторе используйте официальное расширение VS Code.

Полезные советы и лучшие практики

• Мигрируйте в отдельной ветке. Не трогайте main до полной проверки в staging.

• Сначала запустите codemод, потом правьте вручную. Автоматика берёт на себя ~80% работы, остальное - ручной разбор.

• Используйте oklch для цветов. Tailwind v4 нативно поддерживает современные цветовые пространства - переходите на oklch для более точных оттенков.

• Не копируйте старый конфиг напрямую. Переосмыслите тему - v4 CSS-синтаксис лаконичнее, и многое можно упростить.

• Следите за changelog. Tailwind v4 активно развивается - читайте github.com/tailwindlabs/tailwindcss/releases.

• Проверяйте консоль браузера после миграции: исчезнувшие классы не дают ошибок JS, только визуальные баги.

Итог

Миграция на Tailwind CSS v4 требует времени, но это разовая инвестиция. Новый движок работает заметно быстрее, конфигурация через CSS - прозрачнее и ближе к нативному коду, а CSS-переменные теперь первоклассный инструмент темизации.

Ключевые шаги: обновить зависимости, запустить @tailwindcss/upgrade, перенести конфиг в @theme, обновить импорт, исправить устаревшие утилиты. Большинство проблем - из-за пропущенных переименований и старого PostCSS-конфига.

Если после миграции что-то идёт не так - первым делом проверьте CSS-импорт, наличие tailwind.config.js и устаревшие имена классов.