0
# @vitejs/plugin-react-refresh
1

2
@vitejs/plugin-react-refresh is a Vite plugin that provides React Refresh (Fast Refresh) support for React applications during development. It integrates with Vite's development server to enable hot module replacement (HMR) that preserves React component state while reloading code changes, providing instant feedback during development with minimal configuration.
3

4
## Package Information
5

6
- **Package Name**: @vitejs/plugin-react-refresh
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install @vitejs/plugin-react-refresh`
10

11
## Core Imports
12

13
```javascript
14
import reactRefresh from '@vitejs/plugin-react-refresh';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const reactRefresh = require('@vitejs/plugin-react-refresh');
21
```
22

23
## Basic Usage
24

25
```javascript
26
// vite.config.js
27
import reactRefresh from '@vitejs/plugin-react-refresh';
28

29
export default {
30
  plugins: [reactRefresh()]
31
};
32
```
33

34
With TypeScript:
35

36
```typescript
37
// vite.config.ts
38
import { defineConfig } from 'vite';
39
import reactRefresh from '@vitejs/plugin-react-refresh';
40

41
export default defineConfig({
42
  plugins: [reactRefresh()]
43
});
44
```
45

46
## Architecture
47

48
The plugin operates at build time as part of Vite's plugin system:
49

50
- **Plugin Factory**: Main export is a function that returns a Vite plugin object
51
- **Babel Integration**: Uses Babel plugins to transform React components with refresh boundaries
52
- **Runtime Injection**: Automatically injects React Refresh runtime code into the development bundle
53
- **File Processing**: Processes JSX/TSX files matching configurable include/exclude patterns
54
- **Development Only**: Automatically disables in production builds
55

56
## Capabilities
57

58
### Plugin Factory
59

60
Creates a Vite plugin with React Refresh support.
61

62
```javascript { .api }
63
/**
64
 * Creates a Vite plugin that enables React Refresh for development
65
 * @param options - Optional configuration for the plugin
66
 * @returns Vite plugin object with React Refresh capabilities
67
 */
68
function reactRefresh(options?: Options): import('vite').Plugin;
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
// Basic usage
75
import reactRefresh from '@vitejs/plugin-react-refresh';
76

77
export default {
78
  plugins: [reactRefresh()]
79
};
80

81
// With custom parser plugins for experimental syntax
82
export default {
83
  plugins: [
84
    reactRefresh({
85
      parserPlugins: ['classProperties', 'classPrivateProperties']
86
    })
87
  ]
88
};
89

90
// With custom include/exclude patterns
91
export default {
92
  plugins: [
93
    reactRefresh({
94
      include: '**/*.tsx',
95
      exclude: [/\.stories\.(t|j)sx?$/, /node_modules/]
96
    })
97
  ]
98
};
99
```
100

101
### Preamble Code Access
102

103
Access to the preamble code used for React Refresh runtime setup.
104

105
```javascript { .api }
106
/**
107
 * Preamble code injected into HTML for React Refresh runtime initialization
108
 * @type {string}
109
 */
110
reactRefresh.preambleCode: string;
111
```
112

113
**Usage Example:**
114

115
```javascript
116
// Access preamble code for custom HTML injection
117
import reactRefresh from '@vitejs/plugin-react-refresh';
118

119
console.log(reactRefresh.preambleCode);
120
// Contains the runtime setup code for React Refresh
121
```
122

123
## Types
124

125
### Options Interface
126

127
Configuration options for the React Refresh plugin.
128

129
```typescript { .api }
130
interface Options {
131
  /** 
132
   * Additional Babel parser plugins to enable for experimental syntax
133
   * @example ['classProperties', 'decorators-legacy'] 
134
   */
135
  parserPlugins?: ParserOptions['plugins'];
136
  
137
  /** 
138
   * Files to include for React Refresh processing
139
   * @default /\.(t|j)sx?$/
140
   * @example '**/*.tsx' or [/\.tsx$/, /\.jsx$/]
141
   */
142
  include?: string | RegExp | Array<string | RegExp>;
143
  
144
  /** 
145
   * Files to exclude from React Refresh processing  
146
   * @default /node_modules/
147
   * @example [/\.stories\.(t|j)sx?$/, /node_modules/]
148
   */
149
  exclude?: string | RegExp | Array<string | RegExp>;
150
}
151
```
152

153
### Plugin Type
154

155
Vite plugin object returned by the factory function. The plugin conforms to Vite's Plugin interface and implements the following hooks:
156

157
```typescript { .api }
158
// The plugin returns a standard Vite Plugin object with these key properties:
159
interface ReactRefreshPlugin extends import('vite').Plugin {
160
  /** Plugin identifier */
161
  name: 'react-refresh';
162
  
163
  /** Plugin execution order - runs before other plugins */
164
  enforce: 'pre';
165
}
166
```
167

168
### Babel Parser Options
169

170
Extended from @babel/core for parser plugin configuration.
171

172
```typescript { .api }
173
type ParserOptions = {
174
  /** 
175
   * Babel parser plugins to enable
176
   * @example ['jsx', 'typescript', 'decorators-legacy']
177
   */
178
  plugins?: string[];
179
};
180
```
181

182
## Error Handling
183

184
The plugin handles several error scenarios:
185

186
- **Missing Preamble**: Throws error if React Refresh runtime preamble is not detected
187
- **Build Mode**: Automatically skips processing in production builds  
188
- **Invalid Files**: Silently skips files that don't match include/exclude patterns
189
- **Non-React Files**: Skips plain JS/TS files without React imports
190

191
### Middleware Mode Error
192

193
When using Vite in middleware mode, you may encounter this error:
194

195
```
196
@vitejs/plugin-react-refresh can't detect preamble. Something is wrong. 
197
See https://github.com/vitejs/vite-plugin-react/pull/11#discussion_r430879201
198
```
199

200
This occurs when your entry `index.html` file is not transformed with `ViteDevServer.transformIndexHtml`. 
201

202
**Solution**: Explicitly transform your `index.html` in your server setup:
203

204
```javascript
205
app.get('/', async (req, res, next) => {
206
  try {
207
    let html = fs.readFileSync(path.resolve(root, 'index.html'), 'utf-8')
208
    html = await viteServer.transformIndexHtml(req.url, html)
209
    res.send(html)
210
  } catch (e) {
211
    return next(e)
212
  }
213
})
214
```
215

216
## Development Notes
217

218
- **File Processing**: By default processes `.js`, `.jsx`, `.ts`, and `.tsx` files
219
- **Node.js Version**: Requires Node.js 12.0.0 or higher  
220
- **React Components**: Automatically detects React components by uppercase naming convention
221
- **TypeScript Support**: Full support for TypeScript JSX syntax
222
- **ReasonReact**: Special handling for ReasonReact `.bs.js` files
223
- **Middleware Mode**: Requires explicit HTML transformation in custom server setups