Tailwind CSS 4: миграция с v3

Пошаговое руководство по обновлению проекта с Tailwind CSS v3 на v4 с конкретными командами, примерами конфигурации и проверками на 2025–2026 годы. Подробно про breaking changes, обновление зависимостей, тестирование и откат.

• Новая система design tokens: theme.tokens для стабильных семантических переменных (цвета, отступы, радиусы).
• Улучшенная JIT-движок с кешированием на диске и поддержкой incremental rebuilds — ускорение инкрементальных сборок до 2x на локальной машине.
• Переработанная цветовая палитра: дефолтные цвета переподписаны, добавлены HSL-опции и поддержка CSS Color 4 переменных.
• Выпавшие и переработанные плагины: некоторые плагины перестали быть необходимыми (например, aspect-ratio интегрирован в ядро), другие требуют адаптации API.
• Новая структура конфига: рекомендуемая миграция в TypeScript-конфиги (tailwind.config.ts) и возможность разделять tokens в отдельный файл.

Шаг 1: обновление зависимостей

Проверка окружения и обновление пакетов — ключевой и быстрый шаг. На моих проектах обновление по шагам заняло 15–45 минут на локальной машине и ~30 минут на CI (с учётом кешей).

1. Проверка Node и инструментов (1–2 минуты):

   node -v   # ожидается >= v18.12.0
   npm -v

2. Создайте ветку для миграции и зафиксируйте текущее состояние зависимостей:

   git checkout -b migrate/tailwind-4
   git tag pre-tailwind4-$(date +%s)

3. Обновите Tailwind и сопутствующие пакеты. Для npm:

   npm install -D tailwindcss@^4.0.0 postcss@^8.4.0 autoprefixer@^10.4.0

   Если используете yarn или pnpm, команды аналогичны:

   yarn add -D tailwindcss@^4.0.0 postcss@^8.4.0 autoprefixer@^10.4.0
   pnpm add -D tailwindcss@^4.0.0 postcss@^8.4.0 autoprefixer@^10.4.0

4. Если проект использует Next.js, Nuxt или Vite — проверьте совместимость интеграторов. Примеры версий, протестированных в 2026:

   • Next.js >= 13.4.5
   • Nuxt 3 >= 3.4.0
   • Vite >= 5.0.0

5. Обновите локальные скрипты сборки, если используете CLI Tailwind напрямую:

   "build:css": "tailwindcss -i src/styles/input.css -o public/assets/styles.css --minify --config tailwind.config.ts"

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

npm run build:css

Шаг 2: config на CSS

Tailwind 4 рекомендует перенос части настроек в tokens и использование TypeScript-конфигов для более строгой типизации. Это помогает избежать конфликтов при больших дизайн-системах.

Пример минимальной миграции конфигурации: у меня в проекте конфиг весом 300 строк разбился на 3 файла — tokens.ts, tailwind.config.ts, plugins/ui.ts. Ниже показан упрощённый пример.

// tokens.ts
export const tokens = {
  color: {
    primary: 'hsl(220 90% 56%)',
    'primary-600': 'hsl(220 80% 46%)',
    neutral: {
      50: '#fafafa',
      900: '#0b0b0b'
    }
  },
  spacing: {
    px: '1px',
    1: '0.25rem',
    2: '0.5rem',
    4: '1rem'
  }
}

// tailwind.config.ts
import { Config } from 'tailwindcss'
import { tokens } from './tokens'

const config: Config = {
  content: ['./src/**/*.{js,ts,jsx,tsx,vue,html}'],
  theme: {
    tokens: tokens, // новая секция в v4
    extend: {
      colors: {
        primary: tokens.color.primary
      }
    }
  },
  plugins: [require('@tailwindcss/forms')],
}

export default config

Если не готовы к TypeScript, можно оставаться на tailwind.config.cjs, но рекомендую планировать миграцию — типизация помогает отлавливать rename токенов и опечатки при сборке.

Шаг 3: fix breaking changes

Tailwind 4 включает ряд breaking changes; ниже список тех, что встречались наиболее часто при работе с реальными проектами в 2025–2026 годах, и конкретные патчи для них.

1) Переименование цветовых семейств

Некоторые цвета из gray, warmGray и neutral были унифицированы в новые нейтральные токены. Пример фикс-команды (Unix):

# Заменяем text-gray-600 на text-slate-600 в кодовой базе
grep -R --exclude-dir=node_modules "text-gray-600" -l | xargs sed -i 's/text-gray-600/text-slate-600/g'

2) Удалённые/перемещённые утилиты

Утилиты, связанные с aspect-ratio, теперь в ядре — если раньше использовался плагин, удалите его из конфигурации. В то же время некоторые небольшие утилиты были удалены; заменяйте их на эквиваленты с explicit CSS или на кастомные компоненты.

3) Изменение spacing scale

Пара значений spacing получила новую семантику: gap-x-3 теперь соответствует 0.75rem в новых конфигах по умолчанию. Рекомендую прогнать grep по наиболее частым классам и провести визуальную проверку: на проекте из 120 страниц я потратил ~3 часа на ручную корректировку 40 элементов.

4) Плагины с новым API

Если у вас кастомные плагины, которые использовали нетиповой API v2/v3, их нужно адаптировать. Пример обновления плагина:

// old plugin api (v3)
module.exports = function ({ addUtilities }) {
  addUtilities({ '.skew-10': { transform: 'skewY(-10deg)' } })
}

// new plugin api (v4)
import plugin from 'tailwindcss/plugin'
export default plugin(function ({ addUtilities }) {
  addUtilities({ '.skew-10': { transform: 'skewY(-10deg)' } })
})

Проверяйте плагины в списке node_modules и свои локальные плагины. Для сторонних плагинов ищите обновления от авторов или форки, совместимые с Tailwind 4.

Шаг 4: тестирование визуальной регрессии

Тестирование нужно проводить в две стадии: автоматическое и ручное. На моих проектах автоматический скриншотный тест на 200 страницах занял 1.5 часа, ручная проверка ключевых страниц — 2–4 часа.

1. Настройте тесты визуальной регрессии: используйте Playwright или Cypress + Percy/Chromatic. Пример шага в CI (GitHub Actions):

   - name: Run visual tests
     uses: actions/setup-node@v4
     with:
       node-version: 18
   - run: npm ci
   - run: npm run build
   - run: npx playwright test --project=chromium --reporter=list

2. Прогони базовые скриншоты до и после миграции. На моём проекте разница визуально заметна в карточках товаров и в header-меню — это обычно из-за смены spacing и цвета.

3. Составьте чек-лист из 20 критичных мест: header, footer, брендовые секции, формы, карточки товара. Меняйте/фиксите классы по приоритету.

Записывайте время на каждый баг — это поможет оценить объём работы и при необходимости откатиться.

Шаг 5: откат и CI

Готовьте механизм быстрого отката в CI: в большинстве проектов достаточно вернуть тег/ветку и пересобрать. На практике откат в продакшн занимает 15–30 минут при корректно настроенном CI/CD.

• Добавьте в pipeline проверку версии Tailwind: node -e "console.log(require('tailwindcss/package.json').version)".
• Настройте feature-ветку и прогон тестов перед merge — не мержьте миграцию напрямую в main без прогона визуальных тестов и smoke-тестов.
• Если критичные баги обнаружены после деплоя, откат через git revert тега и перезапуск pipeline — самый быстрый путь.

Какие устаревшие классы?

Список устаревших/изменённых классов зависит от ваших кастомизаций, но есть типичные кандидаты, которые чаще всего нужно править вручную:

• text-gray-* → маппинг на text-slate-* или text-neutral-* в зависимости от палитры.
• bg-warmGray-* → замените на соответствующие bg-trueGray-* или токены из theme.tokens.
• gap-x-* / gap-y-* — проверьте соответствие новых значений spacing.
• ring-offset-* — были уточнения в расчётах offset; пересмотрите в интерактивных контролах.
• Плагины: @tailwindcss/aspect-ratio — теперь часть ядра, уберите дублирующие импорты.

Если проект содержит 5k+ файлов шаблонов, используйте автоматические скрипты по замене и прогон тестов. Примеры команд для поиска потенциально проблемных классов:

grep -R "text-gray-" src | wc -l
# затем заменить с ручной проверкой
rg "text-gray-" -n src | sed -n '1,200p' # ripgrep для быстрой навигации

Подготовьте карту замены: составьте CSV или JSON, где для каждого старого класса прописан рекомендованный новый класс. Это ускорит массовую замену через скрипты Node.js или sed.

Что с JIT?

JIT в Tailwind 4 стал ядром сборки: «just-in-time» движок включён по умолчанию и получил несколько улучшений: кеширование на диске, incremental transforms, и лучшую совместимость с фреймворками, генерирующими классы динамически (например, шаблоны с выражениями в JSX/TSX). Это означает, что большинство проектов не должны специально включать режим JIT — он активен автоматом.

Практические рекомендации по JIT в v4:

• Если вы используете динамические классы, добавьте их в safelist в конфиге, особенно если классы формируются на бекенде. Пример:

module.exports = {
  safelist: [
    'bg-primary',
    ...Array.from({ length: 10 }, (_, i) => `text-${i}`)
  ]
}

• Настройте кеширование JIT в CI: сохраняйте папку .tailwind-cache между job'ами. Это сокращает cold build на 20–40%.
• Мониторьте сообщения сборки: Tailwind будет логировать, если обнаружит необработанные динамические шаблоны.

Если возникнут проблемы с недогенерированными классами, сначала проверьте content в конфиге — он должен охватывать все источники (шаблоны, json, mdx и т. п.). Пример содержимого:

content: ['./src/**/*.{js,ts,jsx,tsx,vue,html,mdx}', './components/**/*.{js,ts,jsx,tsx}']

Если вы используете сторонние UI-библиотеки (например, компоненты на основе Tailwind), обязательно проверьте их поддержку v4 — иногда требуется обновление версии UI-библиотеки или патч на fork.

Ссылки на полезные ресурсы внутри сайта: обзор практик по фронтенду — Фронтенд-практики, и подборка материалов по CSS — CSS-руководства.

Проверяйте релиз-ноты и планируйте миграцию как маленькие итерации: на проекте с 2 млн строк кода миграция разбита на 6 спринтов в 2025–2026 годах.

Частые вопросы

Как откатиться на Tailwind 3?

Откат возможен через возврат к сохранённому тегу или ветке. Шаги: 1) обновите package.json к версии tailwindcss@^3.x и удалите конфликтные плагины; 2) откатьте конфигурацию (tailwind.config) к предыдущей версии или используйте backup-файлы; 3) пересоберите проект и прогоните smoke-тесты. На практике полный откат и проверка занимают 15–60 минут при корректном CI. Если вы удаляли старые плагины после обновления, восстановите их версии из package-lock.json или yarn.lock.

Что делать с кастомными плагинами?

Кастомные плагины требуют ревью API: перепишите плагины, используя новый экспорт в формате ES-модулей (export default plugin(...)) и проверьте используемые хуки (addUtilities, matchUtilities). На практике преобразование одного плагина объёмом 80 строк занимает 20–40 минут, включая тестирование. Если плагин использует внутренние нестабильные API Tailwind, лучше заменить логику на чистый CSS или вынести в отдельные компоненты.

Почему сборка стала медленнее в CI?

Если сборки стали медленнее, проверьте кеширование JIT и node_modules. Частые причины: отсутствующий кеш .tailwind-cache, пересборка node_modules на каждом job'е и старые версии GitHub Actions/Runner. Решение: включите кэширование директорий ~/.npm, .tailwind-cache и используйте persistent workspace. В моём кейсе добавление кэша сократило время cold build с 4 минут до 2 минут на CI.

Где посмотреть официальную документацию по миграции?

Официальные релиз-ноты и миграционные гайды публикуются на сайте Tailwind и GitHub в разделе Releases. Для удобства храните ссылку на релиз-ноты в README проекта и закреплённые тикеты с найденными breaking changes. Внутренне документируйте все правки конфигурации и список замен классов: это сильно ускоряет ревью и последующие апдейты.

Сколько времени займёт миграция для среднего проекта?

Примерные оценки зависят от размера и покрытия тестами: для SPA на 200 компонент и ~50 шаблонов — 4–8 часов; для корпоративного сайта с 2000+ шаблонов и кастомными плагинами — 2–5 рабочих дней с учётом визуального тестирования и исправления багов. Планируйте буфер в 20–30% времени на непредвиденные проблемы с UI и сторонними библиотеками.