@vitejs/plugin-react

The official Vite plugin for React with Fast Refresh, automatic JSX runtime, and optional Babel integration.

Quick Reference

Installation: npm install @vitejs/plugin-react

Basic Setup:

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

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

Requirements:

• Node.js: ^20.19.0 || >=22.12.0
• Vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
• React: >= 16.9 (for Fast Refresh)

Performance Decision Matrix:

Core Imports

import react from '@vitejs/plugin-react';

// TypeScript types
import type {
  Options,
  BabelOptions,
  ReactBabelOptions,
  ViteReactPluginApi
} from '@vitejs/plugin-react';

Main API

Plugin Configuration

function react(opts?: Options): Plugin[];

interface Options {
  include?: string | RegExp | Array<string | RegExp>;  // default: /\.[tj]sx?$/
  exclude?: string | RegExp | Array<string | RegExp>;  // default: /\/node_modules\//
  jsxImportSource?: string;                            // default: 'react'
  jsxRuntime?: 'classic' | 'automatic';                // default: 'automatic'
  babel?: BabelOptions | ((id: string, options: { ssr?: boolean }) => BabelOptions);
  reactRefreshHost?: string;                           // for module federation
}

Common Configurations:

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

// Classic JSX runtime (requires React imports)
react({ jsxRuntime: 'classic' })

// Additional file types
react({ include: /\.(mdx|js|jsx|ts|tsx)$/ })

// Module federation
react({ reactRefreshHost: 'http://localhost:3000' })

SSR Preamble

For SSR apps not using transformIndexHtml:

import '@vitejs/plugin-react/preamble';

Usage:

// entry.client.tsx
import '@vitejs/plugin-react/preamble';
import { hydrateRoot } from 'react-dom/client';

hydrateRoot(document.getElementById('root'), <App />);

Error if missing:

Uncaught Error: @vitejs/plugin-react can't detect preamble. Something is wrong.

Access preamble code:

react.preambleCode: string;

Babel Integration

Babel is lazy-loaded and only used when configured. Without Babel config, esbuild/oxc handles all transformations (fastest path).

For detailed Babel configuration, including:

• Static and dynamic configuration options
• Babel Plugin API hooks for other Vite plugins
• Parser plugins for experimental syntax
• React Compiler integration
• Performance optimization strategies
• Transformation pipeline details

See: Babel Integration

Quick Babel Examples:

// Add Babel plugins
react({
  babel: {
    plugins: ['babel-plugin-macros']
  }
})

// Parser plugins only (no transformation overhead)
react({
  babel: {
    parserOpts: {
      plugins: ['decorators-legacy']
    }
  }
})

// Dynamic configuration
react({
  babel: (id, { ssr }) => ({
    plugins: ssr ? ['babel-plugin-ssr'] : ['babel-plugin-client']
  })
})

Architecture

The plugin factory returns multiple Vite plugins that work together:

1. Main Transformer: JSX/TS via esbuild/oxc (default) or Babel (when configured)
2. Fast Refresh Runtime: HMR for React components in development
3. Babel Layer: Optional custom transformations
4. Rolldown Optimizer: Native oxc transforms for Rolldown-vite
5. SSR Support: Preamble initialization

Environment detection is automatic (Vite/Rolldown-vite, dev/prod).

Fast Refresh

Auto-enabled in development for files with JSX or React imports.

Requirements for proper Fast Refresh:

• File should primarily export React components
• Simple constants can be exported alongside components
• Module invalidates only when exports change

Linting: Use eslint-plugin-react-refresh

JSX Runtime Modes

Automatic (default):

• No React import needed in JSX files
• Smaller bundles
• Automatic optimization

Classic:

• Requires import React in all JSX files
• Use: jsxRuntime: 'classic'

Module Federation

Enable HMR across remote and host apps:

// Remote app vite.config.ts
react({ reactRefreshHost: 'http://localhost:3000' })

Updates Fast Refresh runtime from /@react-refresh to http://localhost:3000/@react-refresh.

Note: Include base option if host uses it: http://localhost:3000/{base}

Performance Optimization

Transformation Pipeline Decision

Transformation Matrix:

Optimization Tips

1. Minimize Babel usage: Only use Babel when necessary; let esbuild/oxc handle standard transformations
2. Use static configuration: Avoid function-based babel options when possible
3. Limit file scope: Use include/exclude options to reduce files processed by Babel
4. Lazy loading: Babel is only loaded when needed, so startup time is not affected if Babel is unused

Production Builds

In production builds:

• If no Babel plugins are configured, esbuild handles all transformations (fastest)
• If Babel plugins are configured, Babel transformation is applied
• Fast Refresh code is never included in production builds

Compatibility

Babel Version

The plugin is compatible with Babel 7.x (specifically @babel/core ^7.28.4).

TypeScript

TypeScript syntax is automatically handled without configuration. You don't need @babel/preset-typescript unless you have specific TypeScript transformation requirements beyond standard syntax support.

When you might need @babel/preset-typescript:

• Custom TypeScript transformation options
• Specific legacy TypeScript features
• Integration with other Babel plugins that expect TypeScript preset

React Version

• React >= 16.9: Full support including Fast Refresh
• React < 16.9: Basic transformations work, but Fast Refresh is unavailable

Node.js Version

Requires Node.js ^20.19.0 || >=22.12.0

Troubleshooting

Preamble Error

Error: @vitejs/plugin-react can't detect preamble

Solution: Add import '@vitejs/plugin-react/preamble' to client entry or use transformIndexHtml in SSR.

Fast Refresh Not Working

Check:

• File exports primarily React components
• React version >= 16.9
• No syntax errors preventing module evaluation
• File matches include pattern (default: /.[tj]sx?$/)

Performance Issues

If builds are slow:

• Check if Babel is being used unnecessarily
• Review include/exclude patterns
• Consider if Babel plugins are needed or if parser plugins suffice
• Use static Babel config instead of function-based
• See Babel Integration for detailed performance guidance

TypeScript Issues

TypeScript syntax is automatically handled by esbuild/oxc. You don't need @babel/preset-typescript unless you have specific transformation requirements beyond standard TypeScript syntax.

Reference

Package: @vitejs/plugin-react Type: npm Language: TypeScript (ESM with CommonJS compatibility) Docs: https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react

Babel Compatibility: @babel/core ^7.28.4 React Compatibility: >= 16.9 (< 16.9 works without Fast Refresh)