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

Общее

Чем ECSS отличается от CSS Modules или styled-components?

Логика «какой стиль применить» живёт в .ecss-файле (в условиях @if), а не в компоненте, и полностью типизирована. В браузер попадает статический CSS — без генерации стилей в рантайме. Подробнее — Сравнение.

Нужно ли отказываться от обычного CSS?

Нет. ECSS — надмножество CSS: любой валидный CSS остаётся валидным ECSS. Директивы добавляются по мере необходимости.

Сколько JavaScript попадает в бандл?

Минимум: статический CSS плюс крошечный хелпер, который проставляет класс и data-атрибуты. Никакого вычисления стилей в браузере — см. Как ECSS компилируется.

Поддерживается ли SSR?

Да. Стили — это статический CSS, поэтому SSR работает из коробки. Адаптер Astro рендерит вообще без клиентского JS.

Обязателен ли TypeScript?

Нет, ECSS работает и в JS-проектах. Но в TypeScript вы получаете автодополнение и проверку параметров — см. Интеграция с TypeScript.

Стили и синтаксис

Поддерживаются ли вложенность (&), @media и var()?

Да. CSS-вложенность и нативные at-правила (@media, @supports, @container, …) работают как обычно; var() и кастомные свойства — тоже.

Можно ли использовать синтаксис Sass/SCSS внутри ECSS?

Нет. ECSS — надмножество обычного CSS, а не SCSS: переменные $var, @mixin/@include, @function, циклы @each/@for и подобные конструкции не поддерживаются — многие из них усложняют стили. Часть привычных задач решается средствами ECSS: вложенность (нативный CSS), токены через @const, условия через @if. В будущем планируется аналог миксинов и функций.

Чем @enum отличается от @const?

@enum — список допустимых значений (тип для @param); @const — переиспользуемое значение (токен). См. Перечисления и константы.

Чем extends отличается от @external?

extends — наследование: блок вбирает стили родителя. @external — контекстная стилизация чужого блока внутри текущего, без наследования. См. Наследование.

Компоненты и фреймворки

Почему мой <EButton> рендерится как <div>?

По умолчанию корневой тег компонента — <div>. Укажите нужный через проп as: <EButton as="button">. См. Компоненты и адаптеры.

Можно ли задать HTML-тег прямо в .ecss (как styled.button)?

Нет, и это намеренно. Философия ECSS — описывать только стили и управление их состоянием; всё, что касается разметки, решается на уровне компонента. Поэтому тег задаётся при использовании через проп as: <EButton as="button">, <ECard as="section">.

Как передать обычные атрибуты и обработчики (id, onClick, aria-*)?

Любые пропы, кроме params и as, прокидываются на корневой элемент как есть.

Работает ли ECSS без фреймворка?

Да — адаптер Vanilla JS (DOM) даёт компоненты на чистом DOM API.

Можно ли использовать ECSS в Angular?

Пока нет. Отдельного адаптера для Angular нет (готовые адаптеры — React, Vue, Svelte, SolidJS, Astro и чистый DOM), а интеграция со сборкой сейчас работает только через Vite, который не входит в стандартный тулчейн Angular. Ситуация может измениться с появлением плагинов для webpack и rspack.

Можно ли использовать несколько фреймворков в одном проекте?

Да: зарегистрируйте несколько адаптеров и выбирайте нужный суффиксом ?<id> при импорте. См. Несколько адаптеров.

Можно ли изменить префикс E в имени компонента?

Да, опцией componentNamePrefix у адаптера — см. обзор адаптеров.

Сборка и интеграция

Какие сборщики поддерживаются?

На текущий момент (версия 0.2) — только Vite (@ecss/vite-plugin). Конфигурация (@ecss/config) не привязана к сборщику; в дальнейшем планируется поддержка webpack и rspack.

ECSS компилируется в современный CSS — как быть со старыми браузерами?

ECSS не занимается даунлевелингом: на выходе — обычный современный CSS. Поддержку старых браузеров (вендорные префиксы, полифилы новых возможностей) обеспечивает отдельный шаг постобработки CSS на уровне сборщика — например, Lightning CSS (опционально поддерживается Vite) или PostCSS с Autoprefixer / postcss-preset-env, настроенные через Browserslist.

Есть ли отдельный CLI?

Нет. ECSS работает как плагин сборщика.

Нужно ли коммитить каталог .ecss/?

Нет — он пересоздаётся при каждой сборке. Добавьте .ecss в .gitignore.

Почему ESLint ругается на файлы в папке .ecss/?

.ecss/ — это сгенерированный код (компоненты и типы), а не ваши исходники. Рекомендуется добавить каталог в игнор линтера и форматера, как и в .gitignore: например, ignores: ['.ecss/**'] во flat-конфиге ESLint (или строка .ecss в .eslintignore / .prettierignore).

Есть ли поддержка ECSS в Stylelint?

Нет. Stylelint не понимает директивы ECSS (@block, @param, @if и др.). Ошибки в .ecss уже ловятся на этапе компиляции, а в будущем планируется собственный встроенный линтинг ECSS — без привязки к Stylelint.

Почему импорт .ecss не типизирован?

Скорее всего, не настроен rootDirs в tsconfig. См. Интеграция с TypeScript.