0
# Babel Plugin
1

2
Babel transformation plugin that automatically instruments React components for Fast Refresh support. The plugin analyzes component code and injects the necessary registration and signature calls.
3

4
## Capabilities
5

6
### BabelPlugin
7

8
Main plugin factory function that creates the Babel plugin configuration.
9

10
```javascript { .api }
11
/**
12
 * Babel plugin factory for React Refresh transforms
13
 * @param babel - Babel instance with types and utilities
14
 * @param opts - Plugin configuration options
15
 * @returns Babel plugin configuration object
16
 * @throws Error if not in development environment (unless skipEnvCheck is true)
17
 */
18
function BabelPlugin(babel: any, opts?: BabelPluginOptions): BabelPluginConfig;
19

20
interface BabelPluginOptions {
21
  /** Custom refresh registration function name (default: '$RefreshReg$') */
22
  refreshReg?: string;
23
  /** Custom refresh signature function name (default: '$RefreshSig$') */
24
  refreshSig?: string;
25
  /** Skip development environment check */
26
  skipEnvCheck?: boolean;
27
  /** Emit full signatures instead of hashed keys */
28
  emitFullSignatures?: boolean;
29
}
30

31
interface BabelPluginConfig {
32
  visitor: {
33
    ExportDefaultDeclaration: Function;
34
    FunctionDeclaration: Function;
35
    VariableDeclaration: Function;
36
    Program: Function;
37
    [key: string]: any;
38
  };
39
}
40
```
41

42
**Usage Example:**
43

44
```javascript
45
// babel.config.js
46
module.exports = {
47
  plugins: [
48
    ['react-refresh/babel', {
49
      skipEnvCheck: process.env.NODE_ENV !== 'development',
50
      refreshReg: '$RefreshReg$',
51
      refreshSig: '$RefreshSig$',
52
      emitFullSignatures: false
53
    }]
54
  ]
55
};
56
```
57

58
## Plugin Options
59

60
### refreshReg
61

62
Customize the registration function name used in generated code:
63

64
```javascript
65
// With default options
66
$RefreshReg$(MyComponent, 'MyComponent');
67

68
// With custom refreshReg: 'myCustomReg'
69
myCustomReg(MyComponent, 'MyComponent');
70
```
71

72
### refreshSig
73

74
Customize the signature function name used in generated code:
75

76
```javascript
77
// With default options
78
$RefreshSig$(MyComponent, 'hookSignature', false);
79

80
// With custom refreshSig: 'myCustomSig'
81
myCustomSig(MyComponent, 'hookSignature', false);
82
```
83

84
### skipEnvCheck
85

86
Skip the automatic development environment check:
87

88
```javascript
89
// Plugin normally throws in production unless skipEnvCheck is true
90
{
91
  plugins: [
92
    ['react-refresh/babel', { skipEnvCheck: true }]
93
  ]
94
}
95
```
96

97
### emitFullSignatures
98

99
Control signature key format:
100

101
```javascript
102
// With emitFullSignatures: false (default)
103
$RefreshSig$(MyComponent, 'a8f3k2n9x7', false);
104

105
// With emitFullSignatures: true
106
$RefreshSig$(MyComponent, 'useState{[count, setCount]}(0)', false);
107
```
108

109
## Code Transformations
110

111
The plugin performs several AST transformations:
112

113
### Function Components
114

115
**Input:**
116

117
```javascript
118
function MyComponent() {
119
  const [count, setCount] = useState(0);
120
  return <div>{count}</div>;
121
}
122
```
123

124
**Output:**
125

126
```javascript
127
var _s = $RefreshSig$();
128

129
function MyComponent() {
130
  _s();
131
  const [count, setCount] = useState(0);
132
  return <div>{count}</div>;
133
}
134

135
_s(MyComponent, 'useState{[count, setCount]}(0)', false);
136
```
137

138
### Arrow Function Components
139

140
**Input:**
141

142
```javascript
143
const MyComponent = () => {
144
  const [count, setCount] = useState(0);
145
  return <div>{count}</div>;
146
};
147
```
148

149
**Output:**
150

151
```javascript
152
var _s = $RefreshSig$();
153

154
const MyComponent = () => {
155
  _s();
156
  const [count, setCount] = useState(0);
157
  return <div>{count}</div>;
158
};
159

160
_s(MyComponent, 'useState{[count, setCount]}(0)', false);
161
```
162

163
### Export Default Components
164

165
**Input:**
166

167
```javascript
168
export default function MyComponent() {
169
  return <div>Hello</div>;
170
}
171
```
172

173
**Output:**
174

175
```javascript
176
var _c;
177

178
export default function MyComponent() {
179
  return <div>Hello</div>;
180
}
181

182
_c = MyComponent;
183
$RefreshReg$(_c, 'MyComponent%default%');
184
```
185

186
### Higher-Order Components
187

188
**Input:**
189

190
```javascript
191
const EnhancedComponent = memo(() => {
192
  return <div>Enhanced</div>;
193
});
194
```
195

196
**Output:**
197

198
```javascript
199
var _s = $RefreshSig$();
200
var _c;
201

202
const EnhancedComponent = _c = memo(_s(() => {
203
  _s();
204
  return <div>Enhanced</div>;
205
}, 'hookSignature'));
206

207
$RefreshReg$(_c, 'EnhancedComponent');
208
```
209

210
## Hook Signature Detection
211

212
The plugin automatically detects Hook usage patterns:
213

214
### Built-in Hooks
215

216
- `useState`, `useReducer`, `useEffect`, `useLayoutEffect`
217
- `useMemo`, `useCallback`, `useRef`, `useContext`
218
- `useImperativeMethods`, `useDebugValue`
219

220
### Custom Hooks
221

222
Any function call starting with `use` and a capital letter:
223

224
```javascript
225
function MyComponent() {
226
  const data = useCustomData();
227
  const auth = useAuth();
228
  // etc.
229
}
230
```
231

232
### Signature Generation
233

234
```javascript
235
// Single Hook
236
'useState{[count, setCount]}(0)'
237

238
// Multiple Hooks
239
'useState{[count, setCount]}(0)\nuseEffect{}([count])'
240

241
// Custom Hooks
242
'useCustomHook{}'
243
```
244

245
## Force Reset Comments
246

247
Use special comments to force component remounting:
248

249
```javascript
250
/* @refresh reset */
251

252
function MyComponent() {
253
  // This component will always remount on changes
254
  return <div>Always resets</div>;
255
}
256
```
257

258
## Environment Detection
259

260
The plugin automatically detects the environment:
261

262
```javascript
263
// Automatically enabled in development
264
babel.env() === 'development'
265

266
// Throws error in production unless skipEnvCheck: true
267
babel.env() === 'production' // Error!
268
```
269

270
## Integration Notes
271

272
- Plugin must run before other JSX transforms
273
- Requires React Refresh runtime to be available
274
- Generated code expects `$RefreshReg$` and `$RefreshSig$` to be in scope
275
- Works with TypeScript when using `@babel/preset-typescript`
276
- Compatible with React 16.9+ and all modern bundlers