0
# @vitejs/plugin-react
1

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

4
## Quick Reference
5

6
**Installation:** `npm install @vitejs/plugin-react`
7

8
**Basic Setup:**
9
```typescript
10
import { defineConfig } from 'vite';
11
import react from '@vitejs/plugin-react';
12

13
export default defineConfig({
14
  plugins: [react()],
15
});
16
```
17

18
**Requirements:**
19
- Node.js: ^20.19.0 || >=22.12.0
20
- Vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
21
- React: >= 16.9 (for Fast Refresh)
22

23
**Performance Decision Matrix:**
24

25
| Scenario | Use Babel? | Transformer | Performance |
26
|----------|-----------|-------------|-------------|
27
| Standard React app | No | esbuild/oxc | Fastest |
28
| Custom JSX import (Emotion) | No | esbuild/oxc | Fast |
29
| Need Babel plugins | Yes | Babel + esbuild | Slower |
30
| Parser-only features | Yes (parserOpts only) | esbuild/oxc | Fast |
31
32
## Core Imports
33

34
```typescript
35
import react from '@vitejs/plugin-react';
36

37
// TypeScript types
38
import type {
39
  Options,
40
  BabelOptions,
41
  ReactBabelOptions,
42
  ViteReactPluginApi
43
} from '@vitejs/plugin-react';
44
```
45

46
## Main API
47

48
### Plugin Configuration
49

50
```typescript { .api }
51
function react(opts?: Options): Plugin[];
52

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

63
**Common Configurations:**
64

65
```typescript
66
// Emotion support
67
react({ jsxImportSource: '@emotion/react' })
68

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

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

75
// Module federation
76
react({ reactRefreshHost: 'http://localhost:3000' })
77
```
78

79
### SSR Preamble
80

81
For SSR apps not using `transformIndexHtml`:
82

83
```typescript { .api }
84
import '@vitejs/plugin-react/preamble';
85
```
86

87
**Usage:**
88
```typescript
89
// entry.client.tsx
90
import '@vitejs/plugin-react/preamble';
91
import { hydrateRoot } from 'react-dom/client';
92

93
hydrateRoot(document.getElementById('root'), <App />);
94
```
95

96
**Error if missing:**
97
```
98
Uncaught Error: @vitejs/plugin-react can't detect preamble. Something is wrong.
99
```
100

101
**Access preamble code:**
102
```typescript { .api }
103
react.preambleCode: string;
104
```
105

106
## Babel Integration
107

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

110
For detailed Babel configuration, including:
111
- Static and dynamic configuration options
112
- Babel Plugin API hooks for other Vite plugins
113
- Parser plugins for experimental syntax
114
- React Compiler integration
115
- Performance optimization strategies
116
- Transformation pipeline details
117

118
See: [Babel Integration](./babel-integration.md)
119

120
**Quick Babel Examples:**
121

122
```typescript
123
// Add Babel plugins
124
react({
125
  babel: {
126
    plugins: ['babel-plugin-macros']
127
  }
128
})
129

130
// Parser plugins only (no transformation overhead)
131
react({
132
  babel: {
133
    parserOpts: {
134
      plugins: ['decorators-legacy']
135
    }
136
  }
137
})
138

139
// Dynamic configuration
140
react({
141
  babel: (id, { ssr }) => ({
142
    plugins: ssr ? ['babel-plugin-ssr'] : ['babel-plugin-client']
143
  })
144
})
145
```
146

147
## Architecture
148

149
The plugin factory returns multiple Vite plugins that work together:
150

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

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

159
## Fast Refresh
160

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

163
**Requirements for proper Fast Refresh:**
164
- File should primarily export React components
165
- Simple constants can be exported alongside components
166
- Module invalidates only when exports change
167

168
**Linting:** Use [eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh)
169

170
## JSX Runtime Modes
171

172
**Automatic (default):**
173
- No React import needed in JSX files
174
- Smaller bundles
175
- Automatic optimization
176

177
**Classic:**
178
- Requires `import React` in all JSX files
179
- Use: `jsxRuntime: 'classic'`
180

181
## Module Federation
182

183
Enable HMR across remote and host apps:
184

185
```typescript
186
// Remote app vite.config.ts
187
react({ reactRefreshHost: 'http://localhost:3000' })
188
```
189

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

192
**Note:** Include `base` option if host uses it: `http://localhost:3000/{base}`
193

194
## Performance Optimization
195

196
### Transformation Pipeline Decision
197

198
**Transformation Matrix:**
199

200
| Babel Config | Dev Transformer | Prod Transformer | Speed | Use Case |
201
|--------------|----------------|------------------|-------|----------|
202
| None | esbuild | esbuild | Fastest | Standard React app |
203
| parserOpts only | esbuild | esbuild | Fast | Parsing experimental syntax |
204
| plugins/presets | Babel | Babel | Slower | Custom transformations needed |
205
206
### Optimization Tips
207

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

213
### Production Builds
214

215
In production builds:
216
- If no Babel plugins are configured, esbuild handles all transformations (fastest)
217
- If Babel plugins are configured, Babel transformation is applied
218
- Fast Refresh code is never included in production builds
219

220
## Compatibility
221

222
### Babel Version
223

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

226
### TypeScript
227

228
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.
229

230
**When you might need @babel/preset-typescript:**
231
- Custom TypeScript transformation options
232
- Specific legacy TypeScript features
233
- Integration with other Babel plugins that expect TypeScript preset
234

235
### React Version
236

237
- **React >= 16.9**: Full support including Fast Refresh
238
- **React < 16.9**: Basic transformations work, but Fast Refresh is unavailable
239

240
### Node.js Version
241

242
Requires Node.js ^20.19.0 || >=22.12.0
243

244
## Troubleshooting
245

246
### Preamble Error
247
```
248
Error: @vitejs/plugin-react can't detect preamble
249
```
250
**Solution:** Add `import '@vitejs/plugin-react/preamble'` to client entry or use `transformIndexHtml` in SSR.
251

252
### Fast Refresh Not Working
253
**Check:**
254
- File exports primarily React components
255
- React version >= 16.9
256
- No syntax errors preventing module evaluation
257
- File matches `include` pattern (default: /\.[tj]sx?$/)
258

259
### Performance Issues
260
**If builds are slow:**
261
- Check if Babel is being used unnecessarily
262
- Review `include`/`exclude` patterns
263
- Consider if Babel plugins are needed or if parser plugins suffice
264
- Use static Babel config instead of function-based
265
- See [Babel Integration](./babel-integration.md) for detailed performance guidance
266

267
### TypeScript Issues
268

269
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.
270

271
## Reference
272

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

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