Адаптеры

Адаптер превращает @block-объявления в типизированные компоненты для конкретного фреймворка. Все адаптеры разделяют общий API — он описан на этой странице; страницы конкретных адаптеров показывают только специфику фреймворка.

Адаптер	id	Тип	Что генерирует	Требования
React	react	inline	компонент в .ecss-модуле	React 18+
Vue	vue	inline	компонент в .ecss-модуле	Vue 3.3+
Svelte	svelte	module-based	.svelte-файлы	Svelte 4+
SolidJS	solid	module-based	.jsx-файлы	solid-js 1.8+
Astro	astro	module-based	.astro-файлы	Astro 4/5
Vanilla JS (DOM)	dom	inline	классы в .ecss-модуле	браузер (без фреймворка)

inline — код компонента встраивается прямо в скомпилированный .ecss-модуль. module-based — адаптер генерирует настоящие файлы фреймворка (.svelte/.astro/.jsx) в служебный каталог .ecss/, а импорт ./X.ecss перенаправляется на них. В обоих случаях вы просто импортируете компонент из .ecss-файла — разница незаметна.

Подключение

Адаптер регистрируется в ecss.config.ts через defineConfig из @ecss/config. defaultAdapter указывает, какой адаптер применяется к .ecss-файлам по умолчанию (значение — id адаптера из таблицы выше):

// ecss.config.ts
import { defineConfig } from '@ecss/config';
import { reactAdapter } from '@ecss/react-adapter';

export default defineConfig({
  adapters: [reactAdapter()],
  defaultAdapter: 'react',
});

Несколько адаптеров в одном проекте

В adapters можно зарегистрировать несколько адаптеров сразу — например, Astro для страниц и React для интерактивных островов. Один и тот же @block будет доступен в обоих фреймворках:

// ecss.config.ts
import { defineConfig } from '@ecss/config';
import { astroAdapter } from '@ecss/astro-adapter';
import { reactAdapter } from '@ecss/react-adapter';

export default defineConfig({
  adapters: [astroAdapter(), reactAdapter()],
  defaultAdapter: 'astro',
});

defaultAdapter применяется к обычным импортам ./X.ecss. Чтобы получить компонент для другого адаптера, добавьте к пути query-суффикс ?<id>, где <id> — идентификатор адаптера из таблицы выше (react, vue, svelte, solid, astro, dom):

---
// Astro-страница — адаптер по умолчанию
import { EButton } from './Button.ecss';
---

// React-остров — явно выбираем React-вариант того же блока
import { EButton } from './Button.ecss?react';

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

Общий API

Имя компонента формируется как {префикс}{BlockName} (по умолчанию префикс E): @block Button → EButton. Компонент импортируется напрямую из .ecss-файла.

Проп params

Параметры блока передаются единственным пропом params (в DOM-адаптере — опцией конструктора). Их типы берутся из сгенерированного интерфейса {Block}Params, поэтому передать значение, не входящее в @enum, не получится.

params обязателен, если у блока есть хотя бы один обязательный @param (без ?); иначе его можно опустить.

Проп as

По умолчанию компонент рендерится как <div>. Проп as принимает любой HTML-тег и меняет корневой элемент; типизация сужает набор допустимых атрибутов под выбранный тег (as="a" открывает href, as="button" — type и т.д.).

Исключение — Astro: там as тоже работает, но сужения атрибутов под конкретный тег нет (принимается любой атрибут).

class, style и атрибуты

ECSS задаёт корневому элементу класс блока, CSS-переменные из params и data-атрибуты. То, что вы передаёте компоненту, объединяется с этими значениями: ваш class добавляется к классу блока, style — к CSS-переменным, остальные атрибуты и обработчики попадают на корневой элемент.

Суб-компоненты (@element)

Если в @block объявлены @element, они доступны как вложенные компоненты через статические свойства корневого: <EButton.Icon>. Суб-компоненты поддерживают тот же проп as, но не принимают params.

Опция componentNamePrefix

Все фабрики адаптеров принимают опцию componentNamePrefix — префикс имени компонента (по умолчанию 'E'):

reactAdapter({ componentNamePrefix: 'My' }); // → MyButton, MyCard

Опция	Тип	По умолчанию	Описание
componentNamePrefix	string	'E'	Префикс имени компонента. Первый символ — [A-Z], остальные — [a-zA-Z0-9_].

Некорректный префикс (не подходящий под /^[A-Z][a-zA-Z0-9_]*$/) приводит к ошибке на этапе сборки.

Какой адаптер выбрать

• Используете фреймворк — берите адаптер этого фреймворка (React / Vue / Svelte / SolidJS / Astro).
• Делаете статический сайт или SSR без клиентского JS — Astro (server-rendered, ноль JS в браузере по умолчанию).
• Пишете на чистом JS без фреймворка — Vanilla JS (DOM).

См. также

• Конфигурация — опции adapters и defaultAdapter
• @block — объявление блоков
• @element — суб-компоненты