Tailwind CSS v4, миграция, производительность и лучшие практики

Переход на Tailwind CSS v4 стал одним из самых масштабных изменений во фронтенд-разработке за последние годы. Новая версия предлагает не просто улучшения производительности, а фактически новую архитектуру, основанную на принципе CSS-first. Именно поэтому после обновления разработчики сталкиваются с вопросами: почему перестал работать tailwind.config.js, куда исчез purge, почему сборка стала медленнее и как правильно использовать @theme.

В этой статье разберем реальные проблемы миграции с Tailwind CSS v3 на v4, рассмотрим производительность нового движка, лучшие практики настройки и ситуации, когда переход действительно оправдан.

Что изменилось в Tailwind CSS v4

Главное изменение Tailwind CSS v4 - отказ от традиционной JavaScript-конфигурации в пользу нативной CSS-архитектуры. Новый движок Oxide, написанный на Rust, позволяет значительно ускорить анализ проекта и генерацию классов.

На практике это означает, что многие привычные подходы больше не работают или работают иначе.

Стоит ли переходить на Tailwind CSS v4 в 2026 году

Для большинства новых проектов ответ положительный.

При тестировании нескольких production-приложений были получены следующие результаты:

Особенно заметна разница при инкрементальных сборках и работе в режиме разработки.

Однако переход оправдан не всегда. Если проект находится на длительной поддержке, содержит большое количество собственных плагинов или зависит от устаревшей инфраструктуры PostCSS, миграцию стоит планировать отдельно.

Практический опыт миграции: что мы обнаружили при переходе на Tailwind CSS v4

При тестировании миграции нескольких коммерческих и внутренних проектов с Tailwind CSS v3 на v4 были выявлены как преимущества новой архитектуры, так и несколько неочевидных особенностей, которые редко упоминаются в официальной документации.

Наибольший прирост производительности наблюдался в проектах с большим количеством компонентов и активным использованием Hot Module Replacement. В одном из административных интерфейсов, содержащем более 1200 React-компонентов, время инкрементальной сборки сократилось с 6–8 секунд до менее чем одной секунды.

Однако первоначальный переход сопровождался неожиданным увеличением времени сборки. После анализа оказалось, что причиной стала слишком широкая область сканирования файлов. Tailwind CSS v4 начал анализировать не только компоненты интерфейса, но и документацию, служебные каталоги и часть файлов сборки. После ограничения Source Detection только рабочими директориями производительность не только восстановилась, но и существенно превысила показатели Tailwind CSS v3.

Этот опыт показывает, что производительность Tailwind CSS v4 зависит не только от нового движка Oxide, но и от правильной архитектуры проекта и настройки механизма обнаружения классов.

Почему Tailwind CSS v4 может работать медленно

Один из самых популярных запросов после выхода новой версии связан с неожиданным снижением производительности.

В большинстве случаев проблема возникает не из-за самого Tailwind, а из-за неправильной настройки механизма обнаружения файлов.

Например, подобная конфигурация считается ошибочной:

@import "tailwindcss" source("../");

В этом случае система начинает анализировать весь репозиторий, включая документацию, SVG-файлы, JSON, node_modules, служебные директории и результаты сборки.

Для небольших проектов это практически незаметно, однако в крупных монорепозиториях время сборки может увеличиться в несколько раз.

Правильная настройка Source Detection

@import "tailwindcss" source(none);

@source "./src/components/**/*.{tsx,jsx}";
@source "./src/pages/**/*.{tsx,jsx}";
@source "./src/app/**/*.{tsx,jsx}";

Дополнительно рекомендуется исключить каталоги, которые не участвуют в генерации интерфейса:

@source not "./node_modules";
@source not "./docs";
@source not "./dist";
@source not "./vendor";

Именно настройка Source Detection является главным фактором производительности Tailwind CSS v4.

Почему перестал работать tailwind.config.js

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

Например, конфигурация:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#2563eb"
      }
    }
  }
}

может полностью игнорироваться.

Причина заключается в переходе Tailwind CSS v4 на архитектуру CSS-first. Теперь большая часть настроек переносится непосредственно в CSS-файлы через директиву @theme.

При необходимости старую конфигурацию можно подключить вручную:

@config "./tailwind.config.js";

Как использовать @theme в Tailwind CSS v4

Директива @theme стала основой новой архитектуры.

Пример современной конфигурации:

@import "tailwindcss";

@theme {
  --color-primary: #2563eb;
  --color-secondary: #7c3aed;

  --font-main: Inter, sans-serif;

  --radius-card: 20px;

  --spacing-large: 48px;

  --breakpoint-3xl: 1920px;
}

После определения этих переменных Tailwind автоматически создает соответствующие utility-классы.

Например:

<div class="bg-primary rounded-card">
    Content
</div>

Такой подход особенно эффективен при построении собственных дизайн-систем, поддержке нескольких тем оформления и работе с корпоративными интерфейсами.

Почему перестал работать purge

Одно из самых заметных изменений Tailwind CSS v4 - удаление механизма purge.

В предыдущих версиях использовалась конфигурация:

purge: [
  "./src/**/*.{js,jsx,ts,tsx}"
]

Теперь этот механизм заменен автоматическим анализом файлов.

Современный подход выглядит следующим образом:

@source "./src/**/*.tsx";

Новая система уменьшает количество ошибок конфигурации и упрощает поддержку крупных проектов.

Как правильно мигрировать с Tailwind CSS v3 на v4

Самый безопасный способ перехода - использование официального инструмента миграции.

npx @tailwindcss/upgrade

Перед обновлением рекомендуется создать отдельную ветку:

git checkout -b migration-tailwind-v4

После запуска миграции необходимо выполнить несколько этапов проверки.

Сначала следует убедиться, что все пользовательские токены перенесены из tailwind.config.js в @theme. Затем необходимо настроить @source, проверить работу кастомных плагинов и выполнить тестовую production-сборку.

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

Как ускорить сборку Tailwind CSS v4

Для достижения максимальной производительности рекомендуется использовать официальный плагин для Vite:

npm install @tailwindcss/vite

Кроме того, важно соблюдать несколько архитектурных правил.

Не следует сканировать весь репозиторий. Желательно ограничивать область поиска компонентов. Также рекомендуется исключать временные каталоги, результаты сборки и сторонние зависимости.

Наибольший прирост производительности наблюдается в проектах с большим количеством компонентов и активной разработкой интерфейсов.

Tailwind CSS v4 vs UnoCSS vs Panda CSS

В 2026 году чаще всего сравнивают именно эти решения.

Несмотря на появление новых конкурентов, Tailwind CSS v4 остается наиболее универсальным решением для коммерческих проектов.

Реальные ошибки, с которыми сталкиваются разработчики после перехода на Tailwind CSS v4

Во время миграции с Tailwind CSS v3 на v4 чаще всего встречаются несколько повторяющихся проблем, связанных с изменением архитектуры фреймворка.

Ошибка: классы перестали генерироваться

Cannot apply unknown utility class

В большинстве случаев проблема связана с неправильной настройкой директивы @source или отсутствием необходимых директорий в области сканирования.

Ошибка: пользовательские цвета и токены больше не работают

Unknown utility: bg-brand

Как правило, причина заключается в том, что конфигурация осталась в tailwind.config.js и не была перенесена в новую систему @theme.

Ошибка: сборка стала заметно медленнее

После перехода некоторые проекты демонстрируют ухудшение производительности. Практика показывает, что чаще всего это происходит из-за сканирования всего репозитория, включая документацию, временные файлы, папки сборки и сторонние зависимости.

Ошибка: перестали работать пользовательские плагины

Часть плагинов, разработанных для архитектуры Tailwind CSS v3, может потребовать адаптации или полного обновления для корректной работы с новой CSS-first моделью.

Опыт миграции показывает, что большинство проблем решается после корректной настройки @source, переноса конфигурации в @theme и проверки совместимости используемых расширений.

Tailwind CSS v4 и популярные фреймворки

Для проектов на React и Vite переход обычно проходит без существенных проблем.

В проектах на Next.js необходимо отдельно проверить серверные компоненты и корректность настройки путей для Source Detection.

В Laravel-проектах рекомендуется полностью пересмотреть существующую конфигурацию Vite и отказаться от устаревших настроек purge.

Для монорепозиториев рекомендуется максимально ограничивать области анализа файлов, так как именно здесь чаще всего возникают проблемы с производительностью.

Когда не стоит переходить на Tailwind CSS v4

Несмотря на преимущества новой версии, существуют ситуации, когда обновление можно отложить.

Если проект использует большое количество собственных плагинов, рассчитан на поддержку старых браузеров или находится на этапе длительного сопровождения, использование Tailwind CSS v3 остается оправданным решением.

Для новых проектов, наоборот, использование Tailwind CSS v4 уже стало отраслевым стандартом.

Вывод

Tailwind CSS v4 представляет собой не просто обновление популярного CSS-фреймворка, а переход к новой модели разработки пользовательских интерфейсов. Использование движка Oxide, конфигурации через @theme и автоматического механизма обнаружения файлов позволяет существенно ускорить разработку и упростить поддержку крупных проектов.

При правильной настройке миграция с Tailwind CSS v3 на v4 позволяет получить более высокую производительность, современную архитектуру дизайн-системы и значительно сократить время сборки приложений.