Tailwind classes не применяются: чек-лист починки

Сценарий, который я повторял в разных вариациях много раз. Установил Tailwind, написал <div class="bg-blue-500 p-4">, открыл страницу — и кроме самого текста ничего. Никаких отступов, никакого фона, как будто Tailwind не подключён.

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

1. Файл со стилями не подключен

Tailwind генерит CSS, но кто-то должен его импортировать. Без этого ничего не сработает.

В Tailwind v4 (через плагин @tailwindcss/vite) — простой импорт CSS-файла:

@import "tailwindcss";

Этот файл (src/styles/global.css или подобный) подключаешь в точку входа приложения:

// React/Next
import './styles/global.css';

<!-- Astro layout -->
---
import '../styles/global.css';
---

В Tailwind v3 в CSS-файле было три директивы:

@tailwind base;
@tailwind components;
@tailwind utilities;

Если файл с этим содержимым не импортирован — ничего не работает. Проверь, что DevTools видит этот CSS в загрузках.

2. Content paths не покрывают твой код

Tailwind собирает не все возможные классы — он сканирует исходники и генерит только те, что использованы. Если в конфиге указаны не те пути, классы из твоего файла он просто не увидит.

Tailwind v3 — tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx,vue,astro}',
    './pages/**/*.{js,ts,jsx,tsx}',
  ],
  theme: { extend: {} },
  plugins: [],
};

Tailwind v4 сканирует автоматически, но если у тебя файлы лежат в нестандартных местах (например, контент в content/ или внешний пакет в workspace), может потребоваться явно прописать через @source в CSS:

@import "tailwindcss";
@source "../../packages/ui/**/*.{ts,tsx}";

Если ты пишешь в Markdown-файле классы вроде <div class="..."> и они не работают — проверь, попадает ли формат файла в paths.

3. Динамические имена классов

Tailwind не умеет видеть классы, которые ты собираешь из строк:

// плохо: Tailwind не сгенерит bg-red-500
const color = 'red';
const cls = `bg-${color}-500`;

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

const cls = color === 'red' ? 'bg-red-500' : 'bg-blue-500';

Или задавать список через safelist:

module.exports = {
  content: ['./src/**/*.{ts,tsx}'],
  safelist: ['bg-red-500', 'bg-blue-500', 'bg-green-500'],
};

В v4 эквивалент — добавить в CSS @source-инструкции с конкретными классами или поле safelist в JS-конфиге, если он используется.

4. PostCSS не настроен правильно

Tailwind работает через PostCSS. Если ты ставил Tailwind руками без autoprefixer или без правильного postcss.config.js, в production-сборке стилей может не быть.

Минимальный postcss.config.js для Tailwind v3:

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

В v4 со связкой Vite или Astro лучше использовать официальные плагины (@tailwindcss/vite, @astrojs/tailwind) — они сами всё настраивают и не требуют PostCSS-конфига.

5. Astro: класс не применяется на компонентах из-за scoping

В Astro в .astro-файлах автоматического скоупинга classes у Tailwind нет (он не CSS-in-JS). Но если ты используешь рамочные React/Vue-компоненты внутри Astro и подаёшь им класс через проп — компонент должен принять этот проп и применить его на корневом элементе.

// плохо
function Button({ children }) {
  return <button className="px-4 py-2">{children}</button>;
}

// хорошо
function Button({ children, className = '' }) {
  return <button className={`px-4 py-2 ${className}`}>{children}</button>;
}

Иначе классы на <Button class="mt-4"> в Astro-шаблоне просто потеряются.

6. Build cache

Бывало у меня и такое: всё настроено правильно, но классы из нового файла не появляются. Помогает чистка кэша Vite или Next:

rm -rf .astro .next node_modules/.vite
pnpm dev

Особенно после переключения веток или больших рефакторингов сканер иногда не подхватывает новые файлы.

Алгоритм диагностики

Когда вижу «классы не применяются», иду по этому списку:

• Открываю DevTools → вкладку Sources/Network. Загружается ли вообще Tailwind-CSS? Если нет — стилевой файл не подключён.
• В DevTools на проблемном элементе смотрю Computed. Класс есть в DOM? Применил ли его Tailwind? Если в DOM есть, а правил нет в CSS — Tailwind не сгенерил, проверь content paths.
• Класс динамически собран в коде? Перепиши без шаблонной строки.
• Astro/React-компонент не пробрасывает class? Поправь компонент.
• Если ничего не помогает — чистка кэша.

Что я делаю на старте проекта, чтобы потом не возиться

• Использую официальный плагин фреймворка (@astrojs/tailwind, @tailwindcss/vite, Next-интеграция).
• Один основной CSS-файл, импортированный из layout/корня приложения.
• Никогда не собираю классы из переменных — пишу полные имена.
• В компонентах с пропсом className сразу делаю мердж с дефолтными классами.

Tailwind при правильной настройке практически беспроблемный. Когда «не работает» — это почти всегда одна из шести вещей в списке выше. Десять минут на проверку — и всё подсветится.