Какие проблемы существуют у CSS Modules?
На этой странице
CSS Modules хорошо изолируют классы, но не решают все задачи CSS-архитектуры: остаются проблемы композиции, глобальных стилей, темизации, переиспользования, динамических состояний и читаемости class names.
Вопрос
Что такое CSS Modules и какие у них проблемы?
Главное
CSS Modules превращают локальные классы в уникальные имена.
/* Card.module.css */
.card {
padding: 16px;
}import styles from "./Card.module.css";
const className = styles.card;Это снижает риск конфликтов, но добавляет свои ограничения.
Сложная композиция
Если компонент имеет много вариантов, className может быстро стать громоздким.
const className = [
styles.button,
isPrimary && styles.primary,
isLoading && styles.loading,
isWide && styles.wide,
].filter(Boolean).join(" ");Нужны соглашения или утилиты для сборки классов.
Глобальные стили все равно нужны
CSS Modules не отменяют:
- reset/base styles;
- CSS-переменные;
- стили
body; - стили типографики;
- интеграцию с third-party HTML;
- utility classes, если проект их использует.
Темизация
Темы часто удобнее строить через CSS custom properties, а не через дублирование module-классов.
.card {
background: var(--surface);
color: var(--text);
}Переопределение дочерних компонентов
Локальность классов усложняет ситуацию, когда родителю нужно повлиять на внутренний класс дочернего компонента. Обычно лучше передавать props, CSS-переменные или специально предусмотренные slots/API.
Что важно помнить
- Файлы
*.module.cssподдерживаются Vite и Next.js без настройки; классы становятся уникальными автоматически. - Глобальные стили внутри модуля пишут через
:global(.class). - Переиспользование между модулями — через
composesили общие CSS-переменные. - Для типизации имен классов в TypeScript используют плагины вроде
typescript-plugin-css-modules.
Мини-шпаргалка
- CSS Modules изолируют class names.
- Они не заменяют архитектуру стилей.
- Глобальные base/reset styles все равно нужны.
- Для тем лучше подходят CSS-переменные.
- Сложные варианты требуют соглашений.
- Не стоит ломать инкапсуляцию дочернего компонента через внутренние классы.