Переход на Tailwind 4: куда делся конфигурационный файл
Когда я перешёл на Tailwind 4, первым вопросом было: где tailwind.config.ts?
Ответ — его нет. Совсем. И это не ошибка, это основная идея.
В Tailwind 3 у вас было два мира: токены дизайна в JavaScript-конфигурации, стили — в CSS. Tailwind 4 их объединил: теперь всё живёт внутри CSS. В первый день это кажется странным, а потом начинает выглядеть логично.
Эта статья о практической стороне миграции: что меняется, что ломается и что стоит знать заранее.
Что меняется
Раньше ваши цвета жили так:
// tailwind.config.ts
export default {
theme: {
extend: {
colors: {
ink: '#0B0B0F',
signal: '#3B82F6',
},
},
},
}Теперь так:
/* globals.css */
@import "tailwindcss";
@theme {
--color-ink: #0B0B0F;
--color-signal: #3B82F6;
}Синтаксис другой, результат тот же: классы bg-signal, text-ink работают как прежде.
Но есть одно важное отличие. Каждый токен, объявленный внутри @theme, одновременно является настоящей CSS-переменной. То есть его можно использовать и без классов Tailwind:
.custom-shadow {
box-shadow: 0 2px 12px var(--color-ink);
}В Tailwind 3 для этого токен приходилось дублировать в двух местах — в конфигурации и в CSS-переменной. Теперь источник один. Для меня это оказалось самой очевидной выгодой идеи «CSS-first».
Ловушка со шрифтами
Больше всего времени у меня заняли шрифты. Причина в том, что next/font отдаёт вам не готовое значение, а переменную:
import { Golos_Text } from 'next/font/google'
const golos = Golos_Text({
subsets: ['latin'],
variable: '--font-golos',
})Теперь вы хотите подключить это к @theme. И обычный @theme не сработает: он считает значения статическими и не умеет разрешать ссылку на другую переменную.
Решение — @theme inline:
@theme inline {
--font-sans: var(--font-golos), system-ui, sans-serif;
--font-display: var(--font-unbounded), sans-serif;
--font-mono: var(--font-jetbrains), monospace;
}Ключевое слово inline говорит Tailwind: «не копируй это значение, оставь его ссылкой на переменную». Без него классы шрифтов молча перестают работать — ошибки нет, просто виден шрифт по умолчанию.
Правило: любой токен, ссылающийся на другую CSS-переменную, должен быть в @theme inline.
Плагины и от чего отказаться
Во время миграции я полностью убрал три пакета.
Первый — autoprefixer. Tailwind 4 расставляет префиксы сам, отдельный шаг не нужен.
Второй — библиотека компонентов (у меня это был daisyui). Это необязательно, но я убрал её осознанно: готовые компоненты хороши для быстрого старта, а потом вы боретесь с ними при каждой кастомизации. Раз у меня есть собственная дизайн-система, это был лишний слой.
Третий — лишние строки в конфигурации PostCSS. В Tailwind 4 обычно достаточно одного плагина.
Если у вас есть сторонние плагины Tailwind, проверьте их поддержку четвёртой версии до миграции. Этот урок я усвоил на прошлой миграции на Next 16: вас тормозит не основной пакет, а экосистема вокруг него.
Что ломается
На практике я задел три вещи.
Первое — синтаксис произвольных значений. Места с квадратными скобками (вроде w-[calc(100%-2rem)]) чаще всего продолжают работать, но некоторые требуют проверки.
Второе — всё, что опиралось на конфигурацию. У меня был помощник, читавший токены из tailwind.config.ts. Он перестал работать, потому что файла больше нет. Я перевёл его на чтение CSS-переменной.
Третье — палитра цветов по умолчанию. Некоторые оттенки слегка изменились. Если дизайн завязан на точные цвета, объявляйте свои токены и не опирайтесь на палитру по умолчанию.
Самым приятным оказалось другое: настраивать пути к контенту (content: [...]) больше не нужно вообще. Tailwind 4 находит файлы сам.
Куда делась тёмная тема
В Tailwind 3 тема управлялась настройкой darkMode: 'class'. Вместе с конфигурационным файлом исчезла и она, а вариант теперь объявляете вы сами:
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));На первый взгляд это лишняя работа. На практике оказалось полезнее, потому что условие теперь ваше: я использую не class, а атрибут data-theme, и пишу селектор так, как мне нужно.
Кроме того, токены тоже можно переключать по теме. Для этого пишется обычный CSS вне блока @theme:
:root {
--color-surface: #FFFFFF;
}
[data-theme="dark"] {
--color-surface: #0B0B0F;
}Класс bg-surface работает в обеих темах и берёт нужный цвет без всякого префикса dark:. В Tailwind 3 это было невозможно, потому что там токены были не CSS-переменными, а значениями, разрешаемыми на этапе сборки.
Семантические токены: называйте роль, а не цвет
Это не требование Tailwind 4, но подход CSS-first делает такой шаг естественным.
Во время миграции я переименовал токены. Раньше это были названия цветов, теперь — названия ролей:
@theme {
--color-ink: #0B0B0F;
--color-signal: #3B82F6;
}
:root {
--color-surface: #FFFFFF;
--color-text: var(--color-ink);
--color-accent: var(--color-signal);
--color-border: #E5E5EA;
}Сверху палитра — сырые цвета. Снизу роли, ссылающиеся на палитру.
Разница видна на практике. Если нужно поменять акцентный цвет, вы меняете одну строку. Если же в компонентах напрямую написано text-signal, вам придётся обойти десятки файлов.
Практическое правило: в компонентах используйте только названия ролей. Сырое имя цвета должно встречаться исключительно в объявлении палитры. Эта простая дисциплина в разы удешевляет последующие изменения дизайн-системы.
Порядок миграции
Я шёл в таком порядке и рекомендую его:
- Сначала выпишите всё, что есть в
tailwind.config.ts— цвета, шрифты, отступы, брейкпоинты. Это и есть ваша реальная дизайн-система. - Обновите пакет и упростите конфигурацию PostCSS.
- В
globals.cssнапишите@import "tailwindcss"и создайте блок@theme. - Перенесите токены. Цвета с префиксом
--color-*, шрифты--font-*, отступы--spacing-*. - Шрифты положите отдельно, в
@theme inline. - Удалите старый конфигурационный файл и запустите
bun run build. - Пройдитесь по сайту глазами — особенно по шрифтам и теням.
Последний шаг важен, потому что большинство ошибок миграции Tailwind происходит молча: сборка проходит, класс не применяется, и увидеть это можно только глазами.
Стоит ли оно того
Мой ответ — да, но причина не в скорости.
Главная выгода концептуальная: дизайн-система теперь живёт в одном месте, на своём естественном языке. Дублирование токенов между JavaScript-конфигурацией и CSS исчезает. Новый разработчик открывает globals.css и видит всю палитру — искать отдельный конфигурационный файл не нужно.
Если проект небольшой, миграция займёт час. Если большой и с множеством плагинов — сначала проверьте плагины, основная работа будет именно там.