0
# Configuration
1

2
React Hot Loader provides a comprehensive configuration system that allows customization of hot reload behavior, error handling, performance optimizations, and debugging features.
3

4
## Capabilities
5

6
### Configuration Function
7

8
Sets global configuration options for React Hot Loader behavior.
9

10
```typescript { .api }
11
/**
12
 * Configures how React Hot Loader works
13
 * @param config - Partial configuration object with options to override
14
 */
15
function setConfig(config: Partial<Config>): void;
16

17
interface Config {
18
  /** Specify logLevel, default to 'error', set it to false to disable logs */
19
  logLevel: string;
20
  
21
  /** Callback for component registration */
22
  onComponentRegister: (type: any, uniqueLocalName: string, fileName: string) => any;
23
  
24
  /** Callback for component creation */
25
  onComponentCreate: (type: any, displayName: string) => any;
26
  
27
  /** Allows using SFC without changes, leading to some components not updated */
28
  pureSFC: boolean;
29
  
30
  /** Keep render method unpatched, moving sideEffect to componentDidUpdate */
31
  pureRender: boolean;
32
  
33
  /** Allows SFC to be used, enables "intermediate" components used by Relay */
34
  allowSFC: boolean;
35
  
36
  /** Disable "hot-replacement-render" */
37
  disableHotRenderer: boolean;
38
  
39
  /** Disable "hot-replacement-render" when injection into react-dom are made */
40
  disableHotRendererWhenInjected: boolean;
41
  
42
  /** Show "hot-loader/react-dom" warning */
43
  showReactDomPatchNotification: boolean;
44
  
45
  /** Flag to completely disable RHL for SFC */
46
  ignoreSFC: boolean;
47
  
48
  /** Flag to completely disable RHL for Components */
49
  ignoreComponents: boolean;
50
  
51
  /** Enables or disables hooks treatment */
52
  reloadHooks: boolean;
53
  
54
  /** Default value for AppContainer errorOverlay */
55
  errorReporter: React.ComponentType<HotError>;
56
  
57
  /** Global error overlay */
58
  ErrorOverlay: React.ComponentType<{ errors: Array<HotError> }>;
59
  
60
  /** Controls tail(deferred) update checking */
61
  trackTailUpdates: boolean;
62
}
63

64
interface HotError {
65
  error: Error;
66
  errorInfo?: React.ErrorInfo;
67
}
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
// Basic configuration
74
import { setConfig } from 'react-hot-loader';
75

76
setConfig({
77
  logLevel: 'debug',
78
  reloadHooks: true,
79
  trackTailUpdates: false
80
});
81
```
82

83
```javascript
84
// Advanced configuration with callbacks
85
import { setConfig } from 'react-hot-loader';
86

87
setConfig({
88
  // Logging configuration
89
  logLevel: 'warn', // 'debug', 'log', 'warn', 'error', or false
90
  
91
  // Component lifecycle callbacks
92
  onComponentRegister: (type, name, filename) => {
93
    console.log(`Registered component ${name} from ${filename}`);
94
  },
95
  
96
  onComponentCreate: (type, displayName) => {
97
    console.log(`Created component ${displayName}`);
98
  },
99
  
100
  // Performance optimizations
101
  pureSFC: true,
102
  pureRender: false,
103
  allowSFC: true,
104
  
105
  // Feature toggles
106
  reloadHooks: true,
107
  trackTailUpdates: true,
108
  
109
  // Error handling
110
  showReactDomPatchNotification: true
111
});
112
```
113

114
## Configuration Categories
115

116
### Logging Configuration
117

118
Control logging output and verbosity:
119

120
```javascript
121
import { setConfig } from 'react-hot-loader';
122

123
// Disable all logging
124
setConfig({ logLevel: false });
125

126
// Show only errors
127
setConfig({ logLevel: 'error' });
128

129
// Show warnings and errors
130
setConfig({ logLevel: 'warn' });
131

132
// Show all logs (debug mode)
133
setConfig({ logLevel: 'debug' });
134
```
135

136
### Component Lifecycle Callbacks
137

138
Monitor component registration and creation:
139

140
```javascript
141
setConfig({
142
  onComponentRegister: (type, uniqueLocalName, fileName) => {
143
    // Called when a component is registered for hot reloading
144
    console.log(`🔥 Registered: ${uniqueLocalName} in ${fileName}`);
145
    
146
    // Example: Track component registrations
147
    if (window.__DEV_TOOLS__) {
148
      window.__DEV_TOOLS__.trackComponent(uniqueLocalName, fileName);
149
    }
150
  },
151
  
152
  onComponentCreate: (type, displayName) => {
153
    // Called when a component instance is created
154
    console.log(`⚛️ Created: ${displayName}`);
155
    
156
    // Example: Performance monitoring
157
    if (displayName.includes('Expensive')) {
158
      console.time(`${displayName} render`);
159
    }
160
  }
161
});
162
```
163

164
### Performance Optimization
165

166
Configure hot reload performance settings:
167

168
```javascript
169
setConfig({
170
  // Pure SFC optimization
171
  pureSFC: true, // Treat stateless functional components as pure
172
  
173
  // Render method optimization  
174
  pureRender: false, // Keep render method patching for better compatibility
175
  
176
  // SFC handling
177
  allowSFC: true, // Enable stateless functional component support
178
  ignoreSFC: false, // Don't ignore SFC components
179
  
180
  // Component handling
181
  ignoreComponents: false, // Don't ignore class components
182
  
183
  // Hook reloading
184
  reloadHooks: true, // Enable hook hot reloading
185
  
186
  // Update tracking
187
  trackTailUpdates: true // Track deferred updates for better reliability
188
});
189
```
190

191
### Error Handling Configuration
192

193
Customize error reporting and overlay behavior:
194

195
```javascript
196
import { setConfig } from 'react-hot-loader';
197

198
// Custom error reporter component
199
const CustomErrorReporter = ({ error, errorInfo }) => (
200
  <div style={{ 
201
    position: 'fixed', 
202
    top: 0, 
203
    left: 0, 
204
    right: 0, 
205
    bottom: 0, 
206
    backgroundColor: 'rgba(255, 0, 0, 0.1)',
207
    padding: '20px',
208
    zIndex: 9999
209
  }}>
210
    <h2>🚨 Hot Reload Error</h2>
211
    <p>{error.message}</p>
212
    <details>
213
      <summary>Stack Trace</summary>
214
      <pre>{error.stack}</pre>
215
    </details>
216
  </div>
217
);
218

219
// Global error overlay
220
const GlobalErrorOverlay = ({ errors }) => (
221
  <div className="global-error-overlay">
222
    <h1>Multiple Errors Detected</h1>
223
    {errors.map((error, index) => (
224
      <div key={index} className="error-item">
225
        <h3>Error {index + 1}</h3>
226
        <p>{error.error.message}</p>
227
      </div>
228
    ))}
229
  </div>
230
);
231

232
setConfig({
233
  errorReporter: CustomErrorReporter,
234
  ErrorOverlay: GlobalErrorOverlay,
235
  showReactDomPatchNotification: true
236
});
237
```
238

239
### Advanced Hot Renderer Configuration
240

241
Fine-tune hot rendering behavior:
242

243
```javascript
244
setConfig({
245
  // Disable hot renderer entirely
246
  disableHotRenderer: false,
247
  
248
  // Disable hot renderer only when react-dom patches are detected
249
  disableHotRendererWhenInjected: true,
250
  
251
  // Show notification about react-dom patching
252
  showReactDomPatchNotification: true
253
});
254
```
255

256
## Common Configuration Patterns
257

258
### Development vs Production
259

260
```javascript
261
// Development configuration
262
if (process.env.NODE_ENV === 'development') {
263
  setConfig({
264
    logLevel: 'debug',
265
    reloadHooks: true,
266
    trackTailUpdates: true,
267
    showReactDomPatchNotification: true,
268
    onComponentRegister: (type, name, file) => {
269
      console.log(`🔥 Hot: ${name} @ ${file}`);
270
    }
271
  });
272
}
273

274
// Production - configuration is ignored but safe to call
275
setConfig({
276
  logLevel: false // No effect in production
277
});
278
```
279

280
### Performance-Focused Configuration
281

282
```javascript
283
// Optimize for performance
284
setConfig({
285
  pureSFC: true,
286
  pureRender: true,
287
  allowSFC: true,
288
  trackTailUpdates: false, // Disable for better performance
289
  logLevel: false, // Disable logging overhead
290
  reloadHooks: false // Disable if not using hooks heavily
291
});
292
```
293

294
### Debug-Focused Configuration
295

296
```javascript
297
// Maximum debugging information
298
setConfig({
299
  logLevel: 'debug',
300
  trackTailUpdates: true,
301
  showReactDomPatchNotification: true,
302
  
303
  onComponentRegister: (type, name, fileName) => {
304
    console.group(`🔥 Component Registration`);
305
    console.log(`Name: ${name}`);
306
    console.log(`File: ${fileName}`);
307
    console.log(`Type:`, type);
308
    console.groupEnd();
309
  },
310
  
311
  onComponentCreate: (type, displayName) => {
312
    console.log(`⚛️ Component Created: ${displayName}`, type);
313
  }
314
});
315
```
316

317
### Error-Focused Configuration
318

319
```javascript
320
// Enhanced error handling
321
const DetailedErrorReporter = ({ error, errorInfo }) => {
322
  // Send error to logging service
323
  if (window.errorLogger) {
324
    window.errorLogger.log({
325
      message: error.message,
326
      stack: error.stack,
327
      componentStack: errorInfo?.componentStack,
328
      timestamp: new Date().toISOString()
329
    });
330
  }
331
  
332
  return (
333
    <div className="hot-reload-error">
334
      <h2>Hot Reload Error</h2>
335
      <p>{error.message}</p>
336
      <button onClick={() => window.location.reload()}>
337
        Reload Page
338
      </button>
339
    </div>
340
  );
341
};
342

343
setConfig({
344
  errorReporter: DetailedErrorReporter,
345
  showReactDomPatchNotification: true,
346
  logLevel: 'error'
347
});
348
```
349

350
## Configuration Timing
351

352
Configuration should be set early in the application lifecycle:
353

354
```javascript
355
// ✅ Good: Set configuration before importing components
356
import { setConfig } from 'react-hot-loader';
357

358
setConfig({
359
  logLevel: 'debug',
360
  reloadHooks: true
361
});
362

363
// Import components after configuration
364
import App from './App';
365
import './styles.css';
366
```
367

368
```javascript
369
// ❌ Less effective: Setting configuration after component imports
370
import App from './App'; // Components already processed
371
import { setConfig } from 'react-hot-loader';
372

373
setConfig({ logLevel: 'debug' }); // May not affect already processed components
374
```
375

376
## Default Configuration
377

378
React Hot Loader ships with sensible defaults:
379

380
```javascript
381
// Default configuration (reference only)
382
const defaultConfig = {
383
  logLevel: 'error',
384
  onComponentRegister: null,
385
  onComponentCreate: null,
386
  pureSFC: false,
387
  pureRender: false,
388
  allowSFC: true,
389
  disableHotRenderer: false,
390
  disableHotRendererWhenInjected: true,
391
  showReactDomPatchNotification: true,
392
  ignoreSFC: false,
393
  ignoreComponents: false,
394
  reloadHooks: true,
395
  errorReporter: null, // Uses built-in error reporter
396
  ErrorOverlay: null,
397
  trackTailUpdates: true
398
};
399
```