Конфигурация

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

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

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  },
}

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

​Создание вашего файла конфигурации

Создайте файл конфигурации Tailwind для своего проекта с помощью утилиты Tailwind CLI, включенной после установки пакета npm tailwindcss:

npx tailwindcss init

Это создаст минимальный файл tailwind.config.js в корне Вашего проекта:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

​Использование другого имени файла

Чтобы использовать имя, отличное от tailwind.config.js, передайте его в качестве аргумента в командной строке:

npx tailwindcss init tailwindcss-config.js

Когда вы используете собственное имя файла, вам нужно будет указать его в качестве аргумента командной строки при компиляции CSS с помощью инструмента Tailwind CLI:

npx tailwindcss -c ./tailwindcss-config.js -i input.css -o output.css

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

module.exports = {
  plugins: {
    tailwindcss: { config: './tailwindcss-config.js' },
  },
}

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

@config "./tailwindcss-config.js";

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

Узнайте больше о директиве @config в документации Функции и директивы documentation.

​Использование ESM или TypeScript

Вы также можете настроить Tailwind CSS в ESM или даже в TypeScript:

/** @type {import('tailwindcss').Config} */
export default {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

Когда вы запускаете npx tailwindcss init, мы определяем, является ли ваш проект модулем ES, и автоматически генерируем файл конфигурации с правильным синтаксисом.

Вы также можете явно сгенерировать файл конфигурации ESM, используя флаг --esm:

npx tailwindcss init --esm

Чтобы сгенерировать файл конфигурации TypeScript, используйте флаг --ts:

npx tailwindcss init --ts

​Создание файла конфигурации PostCSS

Используйте флаг -p, если вы хотите также сгенерировать базовый файл postcss.config.js вместе с файлом tailwind.config.js:

npx tailwindcss init -p

Это сгенерирует в Вашем проекте файл postcss.config.js, который выглядит следующим образом:

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

​Строим всю конфигурацию по умолчанию

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

Если вы предпочитаете создать полный файл конфигурации, включающий всю конфигурацию Tailwind по умолчанию, используйте параметр --full:

npx tailwindcss init --full

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

​Варианты конфигурации

​Содержимое

В разделе content вы настраиваете пути ко всем вашим HTML-шаблонам, компонентам JS и любым другим файлам, которые содержат имена классов Tailwind.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{html,js}',
    './components/**/*.{html,js}',
  ],
  // ...
}

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

​Тема

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

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  theme: {
    colors: {
      'blue': '#1fb6ff',
      'purple': '#7e5bef',
      'pink': '#ff49db',
      'orange': '#ff7849',
      'green': '#13ce66',
      'yellow': '#ffc82c',
      'gray-dark': '#273444',
      'gray': '#8492a6',
      'gray-light': '#d3dce6',
    },
    fontFamily: {
      sans: ['Graphik', 'sans-serif'],
      serif: ['Merriweather', 'serif'],
    },
    extend: {
      spacing: {
        '8xl': '96rem',
        '9xl': '128rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

Узнайте больше о теме по умолчанию и о том, как ее настроить, в руководстве по настройке темы.

​Плагины

Раздел plugins позволяет вам регистрировать плагины в Tailwind, которые можно использовать для создания дополнительных утилит, компонентов, базовых стилей или пользовательских вариантов.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/aspect-ratio'),
    require('@tailwindcss/typography'),
    require('tailwindcss-children'),
  ],
}

Узнайте больше о написании собственных плагинов в руководстве по созданию плагинов.

​Пресеты

Раздел presets позволяет вам указать Вашу собственную базовую конфигурацию вместо использования базовой конфигурации Tailwind по умолчанию.

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  presets: [
    require('@acmecorp/base-tailwind-config')
  ],

  // Индивидуальные настройки проекта
  theme: {
    //...
  },
}

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

​Префикс

Опция prefix позволяет вам добавить собственный префикс ко всем сгенерированным Tailwind служебным классам. Это может быть действительно полезно при наложении Tailwind поверх существующего CSS, где могут возникнуть конфликты имен.

Например, вы можете добавить префикс tw-, установив опцию prefix следующим образом:

/** @type {import('tailwindcss').Config} */
module.exports = {
  prefix: 'tw-',
}

Теперь каждый класс будет сгенерирован с настроенным префиксом:

.tw-text-left {
  text-align: left;
}
.tw-text-center {
  text-align: center;
}
.tw-text-right {
  text-align: right;
}
/* и так далее */

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

<div class="tw-text-lg md:tw-text-xl tw-bg-red-500 hover:tw-bg-blue-500">
  <!-- -->
</div>

Модификатор тире для отрицательных значений должен быть добавлен перед вашим префиксом, поэтому -mt-8 станет -tw-mt-8, если вы настроили tw- в качестве префикса:

<div class="-tw-mt-8">
  <!-- -->
</div>

Префиксы добавляются только к классам, созданным Tailwind; префикс не будет добавлен к вашим собственным пользовательским классам.

Это означает, что если вы добавите свою собственную утилиту, например:

@layer utilities {
  .bg-brand-gradient { /* ... */ }
}

…у сгенерированных вариантов не будет вашего настроенного префикса:

.bg-brand-gradient { /* ... */ }
.hover\:bg-brand-gradient:hover { /* ... */ }

Если вы хотите добавить префикс к своим собственным утилитам, просто добавьте префикс в определение класса:

@layer utilities {
  .tw-bg-brand-gradient { /* ... */ }
}

​Важно

Опция important позволяет вам контролировать, должны ли утилиты Tailwind помечаться !important. Это может быть действительно полезно при использовании Tailwind с существующим CSS, который имеет селекторы высокой специфичности.

Чтобы сгенерировать утилиты как !important, установите ключ important в параметрах конфигурации на true:

/** @type {import('tailwindcss').Config} */
module.exports = {
  important: true,
}

Теперь все служебные классы Tailwind будут сгенерированы как !important:

.leading-none {
  line-height: 1 !important;
}
.leading-tight {
  line-height: 1.25 !important;
}
.leading-snug {
  line-height: 1.375 !important;
}
/* и так далее */

Это также относится к любым пользовательским утилитам, которые вы определяете в своем CSS с помощью директивы @layer utilities directive:

/* Input */
@layer utilities {
  .bg-brand-gradient {
    background-image: linear-gradient(#3490dc, #6574cd);
  }
}

/* Output */
.bg-brand-gradient {
  background-image: linear-gradient(#3490dc, #6574cd) !important;
}

​Стратегия селектора

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

Чтобы обойти это, вы можете вместо этого установить important в селектор идентификаторов, например #app:

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  important: '#app',
}

Эта конфигурация будет префикс всех Ваших утилит с данным селектором, эффективно увеличивая их специфичность, не делая их на самом деле !important.

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

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

<html>
<!-- ... -->
<style>
  .high-specificity .nested .selector {
    color: blue;
  }
</style>
<body id="app">
  <div class="high-specificity">
    <div class="nested">
      <!-- Будет red-500 -->
      <div class="selector text-red-500"><!-- ... --></div>
    </div>
  </div>

  <!-- Будет #bada55 -->
  <div class="text-red-500" style="color: #bada55;"><!-- ... --></div>
</body>
</html>

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

​Важный модификатор

Кроме того, вы можете сделать любую утилиту важной, добавив в начало символ !:

<p class="!font-medium font-bold">
  Это будет средний размер, хотя жирный шрифт появится позже в CSS.
</p>

! всегда стоит в начале имени утилиты, после любых вариантов, но перед любым префиксом:

<div class="sm:hover:!tw-font-bold">

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

​Разделитель

Опция separator позволяет вам настроить, какой символ должен использоваться для отделения модификаторов (размеры экрана, hover, focus и т. д.) от названий утилит (text-center, items-end и т. д.).

По умолчанию мы используем двоеточие (:), но это может быть полезно изменить, если вы используете язык шаблонов, например Pug, который не поддерживает специальные символы в имени класса.

/** @type {import('tailwindcss').Config} */
module.exports = {
  separator: '_',
}

​Основные плагины

Раздел corePlugins позволяет полностью отключить классы, которые Tailwind обычно генерирует по умолчанию, если они вам не нужны для Вашего проекта.

Чтобы отключить определенные основные плагины, предоставьте объект для corePlugins, который устанавливает для этих плагинов значение false:

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: {
    float: false,
    objectFit: false,
    objectPosition: false,
  }
}

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

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: [
    'margin',
    'padding',
    'backgroundColor',
    // ...
  ]
}

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

/** @type {import('tailwindcss').Config} */
module.exports = {
  corePlugins: []
}

Вот список всех основных плагинов для справки:

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

Для проектов, которым необходимо создать несколько файлов CSS с использованием разных конфигураций Tailwind, используйте директиву @config, чтобы указать, какой файл конфигурации следует использовать для каждой точки входа CSS:

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

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

Узнайте больше о директиве @config в документации Функции и директивы.

​Ссылки в JavaScript

Часто бывает полезно ссылаться на значения Вашей конфигурации в Вашем собственном клиентском JavaScript - например, для доступа к некоторым из значений Вашей темы при динамическом применении встроенных стилей в компоненте React или Vue.

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

import resolveConfig from 'tailwindcss/resolveConfig'
import tailwindConfig from './tailwind.config.js'

const fullConfig = resolveConfig(tailwindConfig)

fullConfig.theme.width[4]
// => '1rem'

fullConfig.theme.screens.md
// => '768px'

fullConfig.theme.boxShadow['2xl']
// => '0 25px 50px -12px rgba(0, 0, 0, 0.25)'

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

​Типы TypeScript

Мы поставляем собственные типы TypeScript для файла tailwind.config.js, который предоставляет вам всевозможную полезную поддержку IDE и значительно упрощает внесение изменений в вашу конфигурацию без обращения к документации.

Файлы конфигурации, сгенерированные с помощью интерфейса командной строки Tailwind, по умолчанию включают необходимую аннотацию типа, но для ручной настройки типов TypeScript просто добавьте аннотацию типа над объектом конфигурации:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}