Руководство по обновлению

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

Tailwind CSS v4.0 разработан для Safari 16.4+, Chrome 111+ и Firefox 128+. Если вам нужна поддержка старых браузеров, используйте версию 3.4, пока не изменятся требования к поддержке вашего браузера.

Использование инструмента обновления

Если вы хотите обновить проект с версии 3 до версии 4, вы можете использовать наш инструмент обновления, который выполнит большую часть тяжелой работы за вас:

$ npx @tailwindcss/upgrade

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

Инструмент обновления требует Node.js 20 или выше, поэтому убедитесь, что ваша среда обновлена перед его запуском.

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

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

Обновление вручную

Использование PostCSS

В v3 пакет tailwindcss был плагином PostCSS, но в v4 плагин PostCSS находится в отдельном пакете @tailwindcss/postcss.

Кроме того, в v4 импорты и добавление вендорных префиксов теперь выполняются автоматически, поэтому вы можете удалить postcss-import и autoprefixer, если они есть в вашем проекте:

export default {  plugins: {    "postcss-import": {},    tailwindcss: {},    autoprefixer: {},    "@tailwindcss/postcss": {},  },};

Использование Vite

Если вы используете Vite, мы рекомендуем перейти с PostCSS-плагина на наш новый специализированный плагин для Vite, чтобы улучшить производительность и получить лучший опыт разработки:

import { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({  plugins: [    tailwindcss(),  ],});

Использование Tailwind CLI

В v4 Tailwind CLI находится в отдельном пакете @tailwindcss/cli. Обновите ваши команды сборки, чтобы использовать новый пакет:

npx tailwindcss -i input.css -o output.cssnpx @tailwindcss/cli -i input.css -o output.css

Изменения в v3

Вот полный список всех критических изменений в Tailwind CSS v4.0.

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

Требования к браузеру

Tailwind CSS v4.0 разработан для современных браузеров и ориентирован на Safari 16.4, Chrome 111 и Firefox 128. Мы зависим от современных функций CSS, таких как @property и color-mix() для основных функций фреймворка, и Tailwind CSS v4.0 не будет работать в старых браузерах.

Если вам нужна поддержка старых браузеров, мы рекомендуем пока использовать v3.4. Мы активно изучаем режим совместимости, чтобы помочь людям обновиться раньше, и надеемся поделиться новостями о нем в будущем.

Удалены директивы @tailwind

В v4 вы импортируете Tailwind с помощью обычного CSS-выражения @import, а не с помощью директив @tailwind, которые использовались в v3:

@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";

Удалены устаревшие утилиты

Мы удалили все утилиты, которые были устаревшими в v3 и не документировались в течение нескольких лет. Вот список того, что было удалено, вместе с современными альтернативами:

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

Мы переименовали следующие утилиты в v4, чтобы сделать их более согласованными и предсказуемыми:

Обновленные шкалы для теней, радиусов и размытия

Мы переименовали стандартные шкалы для теней, радиусов и размытия, чтобы каждая утилита имела именованное значение. Версии без суффиксов по-прежнему работают для обратной совместимости, но утилиты вида <utility>-sm будут выглядеть иначе, если не обновить их до соответствующих версий <utility>-xs.

Чтобы обновить ваш проект в соответствии с этими изменениями, замените все утилиты v3 на их версии для v4:

<input class="shadow-sm" /><input class="shadow-xs" /><input class="shadow" /><input class="shadow-sm" />

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

Утилита outline теперь устанавливает outline-width: 1px по умолчанию, чтобы быть более согласованной с утилитами border и ring. Кроме того, все утилиты outline-<number> по умолчанию устанавливают outline-style на solid, исключая необходимость объединять их с outline:

<input class="outline outline-2" /><input class="outline-2" />

Ранее утилита outline-none фактически не устанавливала outline-style: none, а вместо этого устанавливала невидимый контур, который по-прежнему отображался в режиме принудительной настройки цветов из соображений доступности.

Чтобы сделать это более понятным, мы переименовали эту утилиту в outline-hidden и добавили новую утилиту outline-none, которая действительно устанавливает outline-style: none.

Чтобы обновить ваш проект в соответствии с этим изменением, замените все использования outline-none на outline-hidden:

<input class="focus:outline-none" /><input class="focus:outline-hidden" />

Изменение ширины кольца по умолчанию

В v3 утилита ring добавляла кольцо шириной 3px. В v4 мы изменили это значение на 1px, чтобы сделать его согласованным с границами и контурами.

Чтобы обновить ваш проект в соответствии с этим изменением, замените все использования ring на ring-3:

<input class="ring ring-blue-500" /><input class="ring-3 ring-blue-500" />

Селектор пространства между элементами

Мы изменили селектор, используемый утилитами space-x-* и space-y-*, чтобы решить серьезные проблемы с производительностью на больших страницах:

/* Before */.space-y-4 > :not([hidden]) ~ :not([hidden]) {  margin-top: 1rem;}/* Now */.space-y-4 > :not(:last-child) {  margin-bottom: 1rem;}

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

Если это изменение вызывает проблемы в вашем проекте, мы рекомендуем перейти на flex или grid макет и использовать gap:

<div class="space-y-4 p-4"><div class="flex flex-col gap-4 p-4">  <label for="name">Name</label>  <input type="text" name="name" /></div>

Использование вариантов с градиентами

В v3 переопределение части градиента с помощью варианта "сбрасывало" весь градиент, поэтому в этом примере цвет to-* становился прозрачным в темном режиме вместо желтого:

<div class="bg-gradient-to-r from-red-500 to-yellow-400 dark:from-blue-500">  <!-- ... --></div>

В v4 эти значения сохраняются, что более согласуется с тем, как работают другие утилиты в Tailwind.

Это означает, что вам может потребоваться явно использовать via-none, если вы хотите "сбросить" трехточечный градиент обратно в двухточечный в определенном состоянии:

<div class="bg-linear-to-r from-red-500 via-orange-400 to-yellow-400 dark:via-none dark:from-blue-500 dark:to-teal-400">  <!-- ... --></div>

Конфигурация контейнера

В v3 утилита container имела несколько параметров конфигурации, таких как center и padding, которые больше не существуют в v4.

Чтобы настроить утилиту container в v4, расширьте её с помощью директивы @utility:

@utility container {  margin-inline: auto;  padding-inline: 2rem;}

Цвет границы по умолчанию

В v3 утилиты border-* и divide-* по умолчанию использовали настроенный вами цвет gray-200. В v4 мы изменили это на currentColor, чтобы сделать Tailwind менее навязчивым и соответствовать стандартам браузеров.

Чтобы обновить ваш проект в соответствии с этим изменением, убедитесь, что вы указываете цвет везде, где используете утилиты border-* или divide-*:

<div class="border border-gray-200 px-2 py-3 ...">  <!-- ... --></div>

Альтернативно, добавьте эти базовые стили в ваш проект, чтобы сохранить поведение v3:

@layer base {  *,  ::after,  ::before,  ::backdrop,  ::file-selector-button {    border-color: var(--color-gray-200, currentColor);  }}

Ширина и цвет кольца по умолчанию

Мы изменили ширину утилиты ring с 3px на 1px и изменили цвет по умолчанию с blue-500 на currentColor, чтобы сделать её более согласованной с утилитами border-*, divide-* и outline-*.

Чтобы обновить ваш проект в соответствии с этими изменениями, замените все использования ring на ring-3:

<button class="focus:ring ..."><button class="focus:ring-3 ...">  <!-- ... --></button>

Затем убедитесь, что вы добавляете ring-blue-500 везде, где полагались на цвет кольца по умолчанию:

<button class="focus:ring-3 focus:ring-blue-500 ...">  <!-- ... --></button>

Альтернативно, добавьте эти переменные темы в ваш CSS, чтобы сохранить поведение v3:

@theme {  --default-ring-width: 3px;  --default-ring-color: var(--color-blue-500);}

Однако обратите внимание, что эти переменные поддерживаются только для совместимости и не считаются идиоматичным использованием Tailwind CSS v4.0.

Изменения в Preflight

Мы внесли несколько небольших изменений в базовые стили в Preflight в v4:

Новый цвет плейсхолдера по умолчанию

В v3 текст плейсхолдера по умолчанию использовал настроенный вами цвет gray-400. В v4 мы упростили это, чтобы использовать текущий цвет текста с 50% прозрачностью.

Вы, вероятно, даже не заметите это изменение (оно может даже улучшить внешний вид вашего проекта), но если вы хотите сохранить поведение v3, добавьте этот CSS в ваш проект:

@layer base {  input::placeholder,  textarea::placeholder {    color: var(--color-gray-400);  }}

Кнопки используют курсор по умолчанию

Теперь кнопки используют cursor: default вместо cursor: pointer, чтобы соответствовать поведению браузера по умолчанию.

Если вы хотите продолжить использовать cursor: pointer по умолчанию, добавьте эти базовые стили в ваш CSS:

@layer base {  button:not(:disabled),  [role="button"]:not(:disabled) {    cursor: pointer;  }}

Отступы диалогов удалены

Теперь Preflight сбрасывает отступы для элементов <dialog>, чтобы обеспечить согласованность с тем, как сбрасываются другие элементы.

Если вы хотите, чтобы диалоги по-прежнему центрировались по умолчанию, добавьте этот CSS в ваш проект:

@layer base {  dialog {    margin: auto;  }}

Использование префикса

Теперь префиксы выглядят как варианты и всегда находятся в начале имени класса:

<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600">  <!-- ... --></div>

При использовании префикса вы по-прежнему должны настраивать переменные темы так, как если бы вы не использовали префикс:

@import "tailwindcss" prefix(tw);@theme {  --font-display: "Satoshi", "sans-serif";  --breakpoint-3xl: 120rem;  --color-avocado-100: oklch(0.99 0 0);  --color-avocado-200: oklch(0.98 0.04 113.22);  --color-avocado-300: oklch(0.94 0.11 115.03);  /* ... */}

Сгенерированные CSS-переменные будут включать префикс, чтобы избежать конфликтов с любыми существующими переменными в вашем проекте:

:root {  --tw-font-display: "Satoshi", "sans-serif";  --tw-breakpoint-3xl: 120rem;  --tw-color-avocado-100: oklch(0.99 0 0);  --tw-color-avocado-200: oklch(0.98 0.04 113.22);  --tw-color-avocado-300: oklch(0.94 0.11 115.03);  /* ... */}

Добавление пользовательских утилит

В версии 3 любые пользовательские классы, которые вы определили в @layer utilities или @layer components, Tailwind воспринимал бы как настоящий служебный класс и автоматически работал бы с такими вариантами, как hover, focusилиlg, с той разницей, что @layer components` всегда был бы первым в сгенерированной таблице стилей.

В v4 мы используем нативные каскадные слои и больше не перехватываем правило @layer, поэтому мы представили API @utility в качестве замены:

@layer utilities {  .tab-4 {    tab-size: 4;  }}@utility tab-4 {  tab-size: 4;}

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

@layer components {  .btn {    border-radius: 0.5rem;    padding: 0.5rem 1rem;    background-color: ButtonFace;  }}@utility btn {  border-radius: 0.5rem;  padding: 0.5rem 1rem;  background-color: ButtonFace;}

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

Порядок наложения вариантов

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

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

<ul class="py-4 first:*:pt-0 last:*:pb-0"><ul class="py-4 *:first:pt-0 *:last:pb-0">  <li>One</li>  <li>Two</li>  <li>Three</li></ul>

Скорее всего, у вас их очень мало, если они вообще есть — варианты прямого дочернего элемента (*) и любые варианты плагинов типографики (prose-headings) являются наиболее вероятными, которые вы можете использовать, и даже тогда только если вы сложили их с другими вариантами.

Переменные в произвольных значениях

В v3 вы могли использовать CSS-переменные как произвольные значения без var(), но последние обновления CSS означают, что это часто может быть неоднозначным, поэтому мы изменили синтаксис для этого в v4, чтобы использовать круглые скобки вместо квадратных.

Чтобы обновить ваш проект в соответствии с этим изменением, замените использование старого сокращенного синтаксиса переменных на новый сокращенный синтаксис переменных:

<div class="bg-[--brand-color]"></div><div class="bg-(--brand-color)"></div>

Стили наведения на мобильных устройствах

В v4 мы обновили вариант hover, чтобы он применялся только тогда, когда основное устройство ввода поддерживает наведение:

@media (hover: hover) {  .hover\:underline:hover {    text-decoration: underline;  }}

Это может создать проблемы, если вы создали свой сайт таким образом, что он зависит от срабатывания наведения при касании на сенсорных устройствах. Если это проблема для вас, вы можете переопределить вариант hover с помощью собственного варианта, который использует старую реализацию:

@custom-variant hover (&:hover);

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

Переход outline-color

Утилиты transition и transition-color теперь включают свойство outline-color.

Это означает, что если вы добавляли контур с пользовательским цветом в фокусе, вы увидите переход цвета от цвета по умолчанию. Чтобы избежать этого, убедитесь, что вы задали цвет контура безусловно или явно задали его для обоих состояний:

<button class="transition hover:outline-2 hover:outline-cyan-500"></button><button class="outline-cyan-500 transition hover:outline-2"></button>

Отключение основных плагинов

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

Использование функции theme()

Поскольку v4 включает CSS-переменные для всех значений вашей темы, мы рекомендуем использовать эти переменные вместо функции theme() везде, где это возможно:

.my-class {  background-color: theme(colors.red.500);  background-color: var(--color-red-500);}

Для случаев, когда вам все еще нужно использовать функцию theme() (например, в медиазапросах, где CSS-переменные не поддерживаются), вы должны использовать имя CSS-переменной вместо старой точечной нотации:

@media (width >= theme(screens.xl)) {@media (width >= theme(--breakpoint-xl)) {  /* ... */}

Использование конфигурационного файла на JavaScript

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

Если вам все еще нужно использовать конфигурационный файл на JavaScript, вы можете загрузить его явно с помощью директивы @config:

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

The corePlugins, safelist, and separator options from the JavaScript-based config are not supported in v4.0. To safelist utilities in v4 use @source inline().

Значения темы в JavaScript

В v3 мы экспортировали функцию resolveConfig , которую вы могли использовать для преобразования вашей конфигурации на основе JavaScript в плоский объект, который можно использовать в другом JavaScript.

Мы удалили это в v4 в надежде, что люди смогут использовать генерируемые нами CSS-переменные напрямую, что намного проще и значительно уменьшит размер вашего бандла.

Например, популярная библиотека Motion для React позволяет анимировать значения CSS-переменных:

<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />

Если вам нужен доступ к значению CSS-переменной в JS, вы можете использовать getComputedStyle, чтобы получить значение переменной темы в корневом элементе документа:

let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");

Использование @apply с Vue, Svelte или CSS-модулями

В v4 таблицы стилей, которые объединяются отдельно от вашего основного CSS-файла (например, файлы CSS-модулей, блоки <style> в Vue, Svelte или Astro и т.д.), не имеют доступа к переменным темы, пользовательским утилитам и пользовательским вариантам, определенным в других файлах.

Чтобы сделать эти определения доступными в этих контекстах, используйте @reference для их импорта без дублирования CSS в вашем бандле:

<template>  <h1>Привет мир!</h1></template><style>  @reference "../../app.css";  h1 {    @apply text-2xl font-bold text-red-500;  }</style>

Альтернативно, вы можете использовать ваши CSS-переменные темы напрямую вместо использования @apply, что также улучшит производительность, поскольку Tailwind не нужно будет обрабатывать эти стили:

<template>  <h1>Привет мир!</h1></template><style>  h1 {    color: var(--text-red-500);  }</style>

Вы можете найти больше документации по использованию Tailwind с модулями CSS.

Использование Sass, Less и Stylus

Tailwind CSS v4.0 не предназначен для использования с препроцессорами CSS, такими как Sass, Less или Stylus. Думайте о самом Tailwind CSS как о вашем препроцессоре — вам не следует использовать Tailwind с Sass по той же причине, по которой вы не используете Sass со Stylus. Из-за этого невозможно использовать Sass, Less или Stylus для ваших таблиц стилей или блоков <style> в Vue, Svelte, Astro и т. д.

Узнайте больше в документации по совместимости.