CSS-модули в React: как они работают и как их использовать

CSS-модули локализуют имена классов в CSS, предотвращая конфликты стилей между компонентами. В React их просто подключать через import и использовать как свойства объекта; для композиции классов служит директива composes. В статье показаны примеры, подходы к миграции, чек-листы и шпаргалка по использованию с Sass.

CSS-модули дают удобный способ делать имена классов локальными по умолчанию. Это устраняет проблему перезаписи стилей при использовании одинаковых имён классов в разных компонентах.

В этой статье вы узнаете, как работают CSS-модули, какие у них преимущества, как применить их в React-проекте и как интегрировать Sass для более мощной организации стилей.

Что такое CSS-модули?

CSS-модуль — это файл стилей, в котором имена классов автоматически локализуются (scope) при сборке. Это значит, что в разных файлах вы можете использовать одинаковые имена классов без конфликта.

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

Пример простого класса в файле styles.module.css:

.btn {
    width: 90px;
    height: 40px;
    padding: 10px 20px;
}

Чтобы использовать этот файл в коде на JavaScript/React, его импортируют как объект:

import styles from "./styles.module.css"

В React вы применяете класс так:

Submit

Во время сборки класс .btn может стать чем-то вроде styles_btn__118346908. Это делает имена уникальными и предотвращает коллизии между компонентами.

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

Как работает компоновка и директива composes

CSS-модули поддерживают композицию стилей через ключевое слово composes. Это позволяет переиспользовать базовые классы в других классах.

Пример:

.btn {
    /* базовые стили */
}

.submit {
    composes: btn;
    background-color: green;
    color: #FFFFFF;
}

Вы также можете импортировать класс из другого CSS-модуля:

.submit {
    composes: primary from "./colors.css";
    background-color: green;
}

Важно: правило composes должно идти перед другими правилами в том же селекторе.

Преимущества CSS-модулей

• Изоляция стилей и отсутствие неожиданных переопределений.
• Удобство размещения стилей рядом с компонентом (локальная ответственность).
• Простая композиция через composes.
• Лучшая читаемость и отладка при большом количестве компонентов.

Ограничения и когда CSS-модули не подходят

• Если требуется глобальная тема, завязанная на селекторах по всему приложению (например, широко используемые reset-стили), потребуется смешивать глобальные и модульные стили.
• Для некоторых библиотек UI, которые ожидают конкретные глобальные селекторы, модульный подход требует адаптации.
• Если проект активно использует сторонние классы и CSS на уровне страницы, миграция на модули потребует дополнительной работы.

CSS-модули в React: как подключить

Как именно вы подключаете CSS-модули в React, зависит от способа создания приложения.

• create-react-app: поддержка CSS-модулей доступна «из коробки» для файлов с именем *.module.css.
• Сборка с нуля: потребуется настройка сборщика (например, webpack) и loader-ы для CSS-модулей.

Требования перед началом:

• Node.js установлен на машине.
• Базовое понимание ES6-модулей.
• Базовое понимание React.

Создание приложения React

Для простоты можно использовать create-react-app:

npx create-react-app react-css-modules

Это создаст папку react-css-modules со всеми зависимостями для старта.

Создание компонента Button

Структура: в src создайте папку Components, в ней — папку Button. В ней будут Button.js и Button.module.css.

Button.js:

export default function Button() {
    return (
        Submit
    )
}

Button.module.css:

.btn {
    width: 90px;
    height: 40px;
    padding: 10px 20px;
    border-radius: 4px;
    border: none;
}

Импорт и использование класса в компоненте:

import styles from "./Button.module.css"

export default function Button() {
    return (
        Submit
    )
}

Это минимальный пример использования одного класса.

Динамика и композиция классов

Чтобы сделать компонент более универсальным, можно принимать prop type и выбирать класс по имени:

import styles from "./Button.module.css"

export default function Button({ type = "primary", label = "Button" }) {
    return (
        {label}
    )
}

Button.module.css с использованием composes:

.btn {
    width: 90px;
    height: 40px;
    padding: 10px 20px;
    border-radius: 4px;
    border: none;
}

.primary {
    composes: btn;
    color: #FFFFFF;
    background-color: #6E41E2;
}

.secondary {
    composes: btn;
    color: #6E41E2;
    background-color: #FFFFFF;
}

Теперь primary и secondary наследуют базовые стили из .btn.

Внешние модули цветов

Чтобы переиспользовать палитру, создайте colors.module.css в src/Components:

.primaryBg {
    background-color: #6E41E2;
}

.secondaryBg {
    background-color: #FFFFFF;
}

.primaryColor {
    color: #FFFFFF;
}

.secondaryColor {
    color: #6E41E2;
}

И используйте эти классы в Button.module.css:

.primary {
    composes: btn;
    composes: primaryColor from "../colors.module.css";
    composes: primaryBg from "../colors.module.css";
}

.secondary {
    composes: btn;
    composes: secondaryColor from "../colors.module.css";
    composes: secondaryBg from "../colors.module.css";
}

Так вы централизуете цвета и сможете менять палитру в одном месте.

Sass с CSS-модулями

Sass добавляет переменные, вложенность и миксины, что делает стили более мощными и поддерживаемыми. Чтобы использовать Sass с CSS-модулями в create-react-app, установите пакет sass и используйте расширение .module.scss:

npm install sass

Затем создавайте файлы типа Button.module.scss и импортируйте их как обычно:

import styles from "./Button.module.scss"

Sass + CSS-модули — хорошая пара для масштабируемого фронтенда.

Шпаргалка: быстрые приёмы и сниппеты

• Импорт модуля:

import styles from "./Component.module.css"

• Применение класса:

• Комбинация классов через библиотеку classnames:

import cn from "classnames"
import styles from "./Button.module.css"

OK

• composes для наследования базового набора правил.

Чек-лист по ролям

Разработчик:

• Создать .module.css/.module.scss рядом с компонентом.
• Импортировать как объект и использовать className={styles.foo}.
• Использовать composes для общих базовых стилей.
• Покрыть изменения тестами и визуально проверить компоненты.

Дизайнер:

• Предоставить палитру и токены (переменные Sass или отдельный модуль цветов).
• Определить базовые локи для компонентов (btn, form-control и т.д.).

Код-ревьювер:

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

Мини-методология внедрения CSS-модулей в проект

1. Начните с новых компонентов — создавайте стили как .module.css.
2. Выделите глобальные правила (reset, типографика) в единый глобальный файл.
3. Постепенно мигрируйте крупные части UI, создавая модульные аналоги.
4. Централизуйте цвета и токены в одном модуле (colors.module.css или переменные Sass).
5. Покройте UI-тестами и визуально проверьте важные экраны.

Миграция с глобальных CSS на CSS-модули: советы

• Сначала отделите глобальные нейтральные стили (reset, grid, типографику).
• Переносите компоненты по очереди, оставляя хук-адаптеры для сторонних библиотек.
• Для библиотек, ожидающих глобальные классы, используйте небольшую прослойку, которая мапит модульные имена на требуемые селекторы.

Когда CSS-модули не решат всех задач

• Темing, требующий смены стилей на уровне всей страницы, иногда удобнее реализовать через CSS-переменные в :root и минимальный глобальный слой.
• Для глобальных утилит (например, набор утилит типа margin-top-8) стоит оставить отдельный глобальный модуль.

Глоссарий в одну строку

• CSS-модуль — CSS-файл, имена классов которого локализуются сборщиком для предотвращения коллизий.
• composes — директива для композиции классов в CSS-модулях.
• .module.css/.module.scss — соглашение об именовании для включения локального scope.

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

Как подключить CSS-модули в проект без create-react-app?

Нужно настроить сборщик (webpack) и включить соответствующие loader-ы (css-loader с опцией modules). Точные настройки зависят от версии webpack.

Можно ли использовать глобальные классы вместе с CSS-модулями?

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

Нужно ли ставить префиксы к именам файлов?

Рекомендуется использовать .module.css или .module.scss — это стандартное соглашение, которое понимают многие сборщики.

Краткое резюме

• CSS-модули изолируют имена классов и уменьшают конфликты стилей.
• В React импорт производится как объект, а классы применяются через styles.className.
• Для композиции стилей используется composes; для более мощных возможностей — Sass.
• Миграцию лучше делать постепенно: глобальные правила отдельно, компоненты переводить по одному.

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