Импортозамещение Emotion: пошаговая инструкция с нуля на примере Vanilla Extract

Библиотека Emotion долгое время была одним из лидеров в мире CSS-in-JS для React-приложений, предлагая мощный API и высокую гибкость. Однако в контексте импортозамещения и желания снизить зависимость от зарубежных решений, многие команды ищут альтернативы. Одной из самых перспективных и современной является Vanilla Extract — CSS-инструментарий, который компилируется в статические CSS-классы, предлагая типобезопасность и отличную производительность. Давайте разберем пошаговый процесс миграции с Emotion на Vanilla Extract с нуля.

Шаг 1: Оценка и подготовка. Прежде всего, проанализируйте вашу кодовую базу. Определите, какие возможности Emotion вы используете активно: динамические стили на основе пропсов? Глобальные стили? Темызирование? Ключевые вставки (keyframes)? Vanilla Extract поддерживает большинство из этих концепций, но иначе. Создайте новый branch в вашем репозитории для экспериментов. Убедитесь, что ваш проект использует современный сборщик (Vite, Webpack 5) или фреймворк (Next.js 12+), так как Vanilla Extract требует настройки препроцессинга.

Шаг 2: Установка и базовая настройка. Установите необходимые пакеты. Для проекта на Vite это будет выглядеть так:
npm install @vanilla-extract/css @vanilla-extract/vite-plugin
Далее, нужно сконфигурировать плагин в `vite.config.ts`:
import { defineConfig } from 'vite';
import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
export default defineConfig({
 plugins: [vanillaExtractPlugin()]
});
Для Next.js используется `@vanilla-extract/next-plugin`, для Webpack – свой плагин. После установки плагина, система сборки начнет обрабатывать файлы с расширением `.css.ts`.

Шаг 3: Создание первых стилей. В Emotion вы создавали стили с помощью `css` prop или `styled` компонентов. В Vanilla Extract вы создаете отдельный файл, например, `Button.css.ts`. Внутри него вы определяете стили с помощью функции `style`:
import { style } from '@vanilla-extract/css';
export const button = style({
 padding: '12px 24px',
 backgroundColor: 'blue',
 color: 'white',
 borderRadius: '8px',
});
Этот код скомпилируется в статический CSS-класс (что-то вроде `.button_sha256`). В вашем React-компоненте импортируйте этот класс и применяйте его:
import { button } from './Button.css.ts';
function MyButton() {
 return Click me;
}
Это основа. Вы уже получили типобезопасность – попытка указать несуществующее CSS-свойство вызовет ошибку TypeScript.

Шаг 4: Работа с динамическими пропсами и темами. Emotion позволял вставлять пропсы в стили через функцию. Vanilla Extract использует другой подход – вы создаете вариации (variants) с помощью функции `recipe` (из пакета `@vanilla-extract/recipes`) или динамически вычисляемые классы.
Создание темы: создайте файл `theme.css.ts` и определите контракт:
import { createTheme } from '@vanilla-extract/css';
export const [themeClass, themeVars] = createTheme({
 color: {
 primary: 'blue',
 background: 'white'
 }
});
Теперь используйте `themeVars` в ваших стилях:
export const button = style({
 backgroundColor: themeVars.color.primary,
});
Чтобы применить тему, оберните ваше приложение в div с классом `themeClass`.

Шаг 5: Замена глобальных стилей и keyframes. Глобальные стили в Emotion (`Global` компонент) заменяются на файлы `global.css.ts` с использованием функции `globalStyle`:
import { globalStyle } from '@vanilla-extract/css';
globalStyle('body', {
 margin: 0,
 fontFamily: 'Arial'
});
Анимации `keyframes` создаются с помощью функции `keyframes` и используются аналогично.

Шаг 6: Поэтапная миграция и coexistence. Не пытайтесь мигрировать всё приложение за один день. Начните с небольших, изолированных компонентов (кнопки, инпуты). Вы можете временно использовать обе библиотеки в одном проекте. Постепенно заменяйте компоненты, написанные с Emotion, на новые, использующие Vanilla Extract. Это позволит команде адаптироваться и тестировать изменения.

Шаг 7: Анализ результатов. После миграции ключевых компонентов проанализируйте bundle size. Vanilla Extract, генерируя статический CSS, обычно дает выигрыш в размере итогового бандла по сравнению с runtime-библиотеками вроде Emotion. Проверьте производительность рендеринга – отсутствие runtime-вычислений стилей должно положительно сказаться на FCP (First Contentful Paint).

Преимущества перехода: типобезопасность CSS, нулевой runtime, отличная производительность, статическое извлечение CSS. Сложности: необходимость переписывания логики динамических стилей, другая ментальная модель (не inline-стили, а классы), настройка сборки.
Этот путь требует усилий, но результат – современная, производительная и независимая кодовая база стилей, соответствующая актуальным трендам и стратегии технологического суверенитета.