Быстрый старт

Это руководство проведёт через подключение ECSS к проекту на Vite. В примерах используется React, но ECSS работает с любым поддерживаемым фреймворком — достаточно подключить соответствующий адаптер.

Установка

Понадобятся три пакета: плагин сборщика, общий конфиг и адаптер для вашего фреймворка.

npm

npm i -D @ecss/vite-plugin @ecss/config @ecss/react-adapter

pnpm

pnpm add -D @ecss/vite-plugin @ecss/config @ecss/react-adapter

yarn

yarn add -D @ecss/vite-plugin @ecss/config @ecss/react-adapter

Подключение плагина

Добавьте плагин ECSS в vite.config.ts — перед плагином фреймворка:

// vite.config.ts
import ecss from '@ecss/vite-plugin';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [ecss(), react()],
});

Настройка адаптера

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

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

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

Настройка TypeScript

При сборке ECSS генерирует типы для каждого .ecss-файла в каталог .ecss/types. Чтобы TypeScript подхватывал их при импорте *.ecss, добавьте этот каталог в rootDirs:

// tsconfig.json (или tsconfig.app.json)
{
  "compilerOptions": {
    "rootDirs": [".", "./.ecss/types"]
  }
}

Каталог .ecss/ пересоздаётся при каждой сборке — добавьте его в .gitignore:

# .gitignore
.ecss

Первый .ecss-файл

Создайте src/Button.ecss. Объявите перечисление вариантов, блок с параметром и условные стили:

/* src/Button.ecss */
@enum Variant {
  values: "primary", "ghost";
}

@block Button {
  @param --variant Variant;

  display: inline-flex;
  padding: 10px 20px;
  border-radius: 6px;
  border: none;
  cursor: pointer;

  @if (--variant == "primary") {
    background: #646cff;
    color: #fff;
  }

  @if (--variant == "ghost") {
    background: transparent;
    color: #646cff;
    border: 1px solid currentColor;
  }
}

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

Импортируйте сгенерированный компонент EButton напрямую из .ecss-файла и передайте параметры:

// src/App.tsx
import { EButton } from './Button.ecss';

export function App() {
  return (
    <EButton as="button" params={{ variant: 'primary' }}>
      Кнопка
    </EButton>
  );
}

Запустите dev-сервер — ECSS скомпилирует .ecss-файлы в статический CSS и сгенерирует типизированный компонент:

npm

npm run dev

pnpm

pnpm dev

yarn

yarn dev

TypeScript знает допустимые значения variant из @enum — автодополнение и проверка типов работают сразу, а несуществующий вариант передать не получится.

Что дальше?

• Сравнение — чем ECSS отличается от других решений
• Модульная система — разбивка стилей на несколько файлов
• @block — основная директива и полный синтаксис
• Адаптеры: React — опции генерации компонентов
• Конфигурация — все опции ecss.config