Vite и React: плагин @vitejs/plugin-react

Интеграция React в Vite основана на концепции плагинов Rollup-совместимой системы. В основе лежит официальный плагин @vitejs/plugin-react, который обеспечивает трансформацию JSX, поддержку Fast Refresh и корректную работу React в dev- и production-сборках.

Vite сам по себе не навязывает фреймворк. Он предоставляет минимальный runtime для разработки и делегирует фреймворк-специфичные преобразования плагинам. В случае React именно этот плагин отвечает за:

  • трансформацию JSX и TSX
  • интеграцию Fast Refresh
  • настройку Babel или SWC пайплайна
  • поддержку HMR на уровне компонентов
  • корректную сборку production-кода через Rollup

Таким образом, React в Vite — это не встроенная функция, а подключаемый слой компиляции и оптимизации.

Установка и базовая интеграция

Основной способ подключения React в Vite-проекте — установка официального плагина и добавление его в конфигурацию Vite.

В типичном проекте используются две зависимости:

  • React runtime
  • React DOM renderer
  • Vite React plugin

Плагин подключается в конфигурации vite.config.js или vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

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

После этого Vite автоматически начинает обрабатывать файлы .jsx и .tsx, применяя нужные трансформации.

JSX трансформация: классический Babel vs SWC

Плагин React для Vite поддерживает два основных режима трансформации JSX:

Babel-пайплайн

По умолчанию используется Babel, который обеспечивает:

  • стабильную совместимость со всеми React-экосистемными инструментами
  • поддержку сложных Babel-плагинов
  • предсказуемую трансформацию JSX

Babel используется внутри плагина через внутреннюю конфигурацию, без необходимости вручную создавать .babelrc.

SWC-пайплайн

Современная альтернатива — использование SWC, включаемое через опцию:

react({
  babel: {
    plugins: []
  },
  jsxRuntime: 'automatic'
})

В новых версиях Vite возможно переключение на SWC-подход для ускорения трансформации. SWC обеспечивает:

  • значительное ускорение холодного старта
  • уменьшение времени трансформации больших файлов
  • упрощённый pipeline без сложных Babel-плагинов

JSX Runtime: classic vs automatic

React поддерживает два режима JSX runtime:

Classic runtime

Требует явного импорта React в каждом файле:

import React from 'react'

JSX компилируется в вызовы React.createElement.

Automatic runtime

Современный режим, включающийся в Vite React plugin по умолчанию:

react({
  jsxRuntime: 'automatic'
})

В этом режиме:

  • импорт React не обязателен
  • используется новый JSX transform
  • уменьшается размер бандла
  • улучшается tree-shaking

Fast Refresh: механизм мгновенного обновления компонентов

Одной из ключевых особенностей интеграции React и Vite является Fast Refresh, реализованный через React Fast Refresh.

Fast Refresh позволяет обновлять компоненты без полной перезагрузки страницы и без потери состояния (в большинстве случаев).

Принцип работы

Fast Refresh основан на следующих этапах:

  1. Vite отслеживает изменения модулей через HMR
  2. плагин React анализирует экспортируемые сущности
  3. определяется, является ли модуль React-компонентом
  4. если да — обновляется только изменённая часть дерева

Сохранение состояния

Состояние сохраняется, если:

  • изменён только JSX или логика рендера
  • не изменена сигнатура компонента
  • не изменены хуки на структурном уровне

Если изменения затрагивают структуру хуков, состояние сбрасывается для предотвращения неконсистентности.

HMR и взаимодействие с Vite

Vite реализует собственную систему HMR поверх ESM. Плагин React интегрируется в этот процесс через трансформационные хуки.

Основные этапы:

  • Vite отслеживает изменение файла
  • выполняет повторную трансформацию через плагин React
  • отправляет обновлённый модуль в браузер
  • React Fast Refresh применяет патч к компонентному дереву

Важно, что Vite не использует Webpack-стиль бандлинга в dev-режиме, что делает обновления практически мгновенными.

Конфигурация плагина React

Плагин предоставляет расширенную настройку поведения:

Опции Babel

react({
  babel: {
    plugins: [
      ['@babel/plugin-proposal-decorators', { legacy: true }]
    ]
  }
})

Используется для добавления кастомных трансформаций JSX или JavaScript.

Включение React Refresh вручную

react({
  fastRefresh: true
})

В современных версиях включено по умолчанию, но может быть отключено для специфичных сборок.

JSX import source

Поддержка кастомного runtime:

react({
  jsxImportSource: '@emotion/react'
})

Используется при работе с CSS-in-JS библиотеками, заменяющими стандартный JSX runtime.

Работа с TypeScript

Vite автоматически поддерживает TSX-файлы при использовании React плагина.

Особенности:

  • TS компиляция выполняется esbuild или SWC на раннем этапе
  • JSX трансформация остаётся за React plugin
  • типы React импортируются через @types/react

Ключевое отличие от классических сборщиков — отсутствие отдельного TypeScript compilation step в dev-режиме.

Производственная сборка

В production режиме Vite использует Rollup. Плагин React выполняет следующие задачи:

  • финальная трансформация JSX
  • удаление development-only кода
  • оптимизация React runtime
  • подготовка модулей для tree-shaking

Благодаря этому итоговый бандл минимизируется без дополнительной настройки.

Совместимость с экосистемой React

Плагин корректно работает с большинством популярных библиотек:

  • React Router
  • Zustand
  • Redux Toolkit
  • React Query
  • Emotion и Styled Components

Особенно важна совместимость с библиотеками, зависящими от HMR, так как Fast Refresh требует корректной идентификации модулей.

Расширенные сценарии использования

Monorepo архитектуры

В monorepo-проектах плагин React в Vite корректно работает с внешними пакетами при условии правильной настройки optimizeDeps.

SSR (Server-Side Rendering)

При использовании SSR плагин участвует только в клиентской части. Серверная сборка требует отдельной конфигурации Vite SSR API, где React plugin остаётся трансформационным слоем.

Library mode

При сборке React-библиотек плагин обеспечивает корректную компиляцию JSX в зависимости от выбранного runtime.

Внутренние оптимизации

Плагин реализует ряд низкоуровневых оптимизаций:

  • кэширование Babel трансформаций
  • инкрементальная пересборка модулей
  • минимизация повторной обработки файлов
  • интеграция с esbuild pre-transform pipeline

Эти механизмы позволяют значительно ускорить dev-сервер даже в крупных React-приложениях.

Ограничения и особенности поведения

Несмотря на высокую скорость работы, существуют особенности:

  • сложные кастомные Babel-плагины могут замедлять сборку
  • некорректные side effects в модулях могут ломать Fast Refresh
  • динамические импорты требуют аккуратной структуры компонентов
  • изменение хуков на лету приводит к reset состояния

Эти ограничения связаны не с Vite напрямую, а с моделью React runtime и HMR.

Оглавление