0
# React Refresh Webpack Plugin
1

2
React Refresh Webpack Plugin enables "Fast Refresh" (Hot Reloading) for React components during development. It integrates with React's Fast Refresh feature to provide instant feedback when editing React components without losing component state, significantly improving the development experience.
3

4
## Package Information
5

6
- **Package Name**: @pmmmwh/react-refresh-webpack-plugin
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install -D @pmmmwh/react-refresh-webpack-plugin react-refresh`
10

11
## Core Imports
12

13
```javascript
14
const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
15
```
16

17
For ES modules:
18

19
```javascript
20
import ReactRefreshPlugin from '@pmmmwh/react-refresh-webpack-plugin';
21
```
22

23
For webpack loader:
24

25
```javascript
26
// webpack.config.js
27
module.exports = {
28
  module: {
29
    rules: [
30
      {
31
        test: /\.[jt]sx?$/,
32
        exclude: /node_modules/,
33
        use: [
34
          {
35
            loader: '@pmmmwh/react-refresh-webpack-plugin/loader',
36
            options: { /* loader options */ }
37
          }
38
        ],
39
      },
40
    ],
41
  },
42
};
43
```
44

45
**Additional Import Patterns:**
46

47
```javascript
48
// Plugin utilities
49
const utils = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
50

51
// Loader utilities  
52
const loaderUtils = require('@pmmmwh/react-refresh-webpack-plugin/loader/utils');
53

54
// Runtime utilities
55
const RefreshUtils = require('@pmmmwh/react-refresh-webpack-plugin/lib/runtime/RefreshUtils');
56

57
// Client utilities
58
const errorHandlers = require('@pmmmwh/react-refresh-webpack-plugin/client/utils/errorEventHandlers');
59
const formatErrors = require('@pmmmwh/react-refresh-webpack-plugin/client/utils/formatWebpackErrors');
60
const retry = require('@pmmmwh/react-refresh-webpack-plugin/client/utils/retry');
61

62
// Overlay components and utilities
63
const theme = require('@pmmmwh/react-refresh-webpack-plugin/overlay/theme');
64
const overlayUtils = require('@pmmmwh/react-refresh-webpack-plugin/overlay/utils');
65

66
// Options utilities
67
const { d, n } = require('@pmmmwh/react-refresh-webpack-plugin/options');
68
```
69

70
## Basic Usage
71

72
```javascript
73
// webpack.config.js
74
const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
75

76
module.exports = {
77
  mode: 'development',
78
  plugins: [
79
    new ReactRefreshPlugin({
80
      overlay: {
81
        sockIntegration: 'wds'
82
      }
83
    }),
84
  ],
85
  module: {
86
    rules: [
87
      {
88
        test: /\.[jt]sx?$/,
89
        exclude: /node_modules/,
90
        use: [
91
          {
92
            loader: 'babel-loader',
93
            options: {
94
              plugins: ['react-refresh/babel'],
95
            },
96
          },
97
        ],
98
      },
99
    ],
100
  },
101
};
102
```
103

104
## Architecture
105

106
The plugin is built around several key components:
107

108
- **ReactRefreshPlugin**: Main Webpack plugin that orchestrates Fast Refresh integration
109
- **ReactRefreshLoader**: Webpack loader that injects React Refresh runtime code into modules
110
- **Error Overlay System**: Built-in error overlay for displaying compilation and runtime errors
111
- **Socket Integrations**: Client-server communication for different development servers (webpack-dev-server, webpack-hot-middleware, webpack-plugin-serve)
112
- **Client Runtime**: Browser-side code that handles module updates and error reporting
113

114
## Capabilities
115

116
### Main Plugin
117

118
Core Webpack plugin that enables React Fast Refresh functionality with comprehensive configuration options.
119

120
```javascript { .api }
121
class ReactRefreshPlugin {
122
  constructor(options?: ReactRefreshPluginOptions);
123
  apply(compiler: import('webpack').Compiler): void;
124
  readonly options: NormalizedPluginOptions;
125
}
126

127
interface ReactRefreshPluginOptions {
128
  esModule?: boolean | ESModuleOptions;
129
  exclude?: string | RegExp | (string | RegExp)[];
130
  forceEnable?: boolean;
131
  include?: string | RegExp | (string | RegExp)[];
132
  library?: string;
133
  overlay?: boolean | ErrorOverlayOptions;
134
}
135
```
136

137
[Plugin Configuration](./plugin-configuration.md)
138

139
### Webpack Loader
140

141
Loader that injects React Refresh HMR code into JavaScript/TypeScript modules.
142

143
```javascript { .api }
144
function ReactRefreshLoader(
145
  this: import('webpack').LoaderContext<ReactRefreshLoaderOptions>,
146
  source: string,
147
  inputSourceMap?: import('source-map').RawSourceMap,
148
  meta?: any
149
): void;
150

151
interface ReactRefreshLoaderOptions {
152
  const?: boolean;
153
  esModule?: boolean | ESModuleOptions;
154
}
155
```
156

157
[Loader Configuration](./loader-configuration.md)
158

159
### Error Overlay System
160

161
Built-in error overlay that displays compilation and runtime errors during development.
162

163
```javascript { .api }
164
interface ErrorOverlayOptions {
165
  entry?: string | false;
166
  module?: string | false;
167
  sockIntegration?: 'wds' | 'whm' | 'wps' | false | string;
168
}
169

170
// Required overlay module exports
171
function handleRuntimeError(error: Error): void;
172
function clearRuntimeErrors(): void;
173
function showCompileError(webpackErrorMessage: string): void;
174
function clearCompileError(): void;
175
```
176

177
[Error Overlay](./error-overlay.md)
178

179
### Socket Integrations
180

181
Pre-built socket integrations for popular development servers.
182

183
```javascript { .api }
184
// Built-in integrations
185
type SocketIntegration = 'wds' | 'whm' | 'wps' | false | string;
186

187
// Integration modules
188
const WDSSocket = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WDSSocket');
189
const WPSSocket = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WPSSocket');
190
const WHMEventSource = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WHMEventSource');
191
```
192

193
[Socket Integrations](./socket-integrations.md)
194

195
### Plugin Utilities
196

197
Core utility functions for advanced plugin integration and customization.
198

199
```javascript { .api }
200
const {
201
  getAdditionalEntries,
202
  getIntegrationEntry,
203
  getSocketIntegration,
204
  injectRefreshLoader,
205
  makeRefreshRuntimeModule,
206
  normalizeOptions,
207
} = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
208
```
209

210
[Plugin Utilities](./plugin-utilities.md)
211

212
### Runtime Utilities
213

214
React Refresh runtime utilities for module boundary detection and registration.
215

216
```javascript { .api }
217
const RefreshUtils = require('@pmmmwh/react-refresh-webpack-plugin/lib/runtime/RefreshUtils');
218

219
interface RefreshUtils {
220
  enqueueUpdate(): void;
221
  executeRuntime(): void;
222
  getModuleExports(moduleId: string): any;
223
  isReactRefreshBoundary(moduleExports: any): boolean;
224
  registerExportsForReactRefresh(moduleId: string, moduleExports: any): void;
225
}
226
```
227

228
[Runtime Utilities](./runtime-utilities.md)
229

230
### Client Utilities
231

232
Browser-side utilities for error handling and connection management.
233

234
```javascript { .api }
235
// Error event handlers
236
const { handleError, handleUnhandledRejection } = require('@pmmmwh/react-refresh-webpack-plugin/client/utils/errorEventHandlers');
237

238
// Error formatting
239
const formatWebpackErrors = require('@pmmmwh/react-refresh-webpack-plugin/client/utils/formatWebpackErrors');
240

241
// Connection retry logic
242
const runWithRetry = require('@pmmmwh/react-refresh-webpack-plugin/client/utils/retry');
243
```
244

245
[Client Utilities](./client-utilities.md)
246

247
## Types
248

249
```javascript { .api }
250
interface ESModuleOptions {
251
  exclude?: string | RegExp | (string | RegExp)[];
252
  include?: string | RegExp | (string | RegExp)[];
253
}
254

255
interface NormalizedPluginOptions extends 
256
  Omit<ReactRefreshPluginOptions, 'overlay'> {
257
  exclude: string | RegExp | (string | RegExp)[];
258
  include: string | RegExp | (string | RegExp)[];
259
  overlay: false | NormalizedErrorOverlayOptions;
260
}
261

262
interface NormalizedErrorOverlayOptions {
263
  entry: string | false;
264
  module: string | false;
265
  sockIntegration: string | false;
266
}
267

268
interface NormalizedLoaderOptions {
269
  const: boolean;
270
  esModule?: boolean | ESModuleOptions;
271
}
272

273
interface HMRMessage {
274
  type: 'ok' | 'warnings' | 'errors' | 'hash' | 'still-ok' | 'invalid';
275
  data?: any;
276
  hash?: string;
277
  warnings?: string[];
278
  errors?: string[];
279
}
280

281
interface FormattedError {
282
  message: string;
283
  stack?: string;
284
  file?: string;
285
  lineNumber?: number;
286
  columnNumber?: number;
287
}
288
```