0
# Socket Integrations
1

2
Pre-built socket integrations enable seamless communication between the error overlay system and popular Webpack development servers for real-time error reporting and Hot Module Replacement coordination.
3

4
## Capabilities
5

6
### Built-in Socket Integrations
7

8
The plugin provides ready-to-use integrations for common development servers.
9

10
```javascript { .api }
11
type SocketIntegration = 'wds' | 'whm' | 'wps' | false | string;
12

13
// Available integration modules
14
const WDSSocket = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WDSSocket');
15
const WPSSocket = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WPSSocket');
16
const WHMEventSource = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WHMEventSource');
17
```
18

19
### Webpack Dev Server Integration (WDS)
20

21
Integration for `webpack-dev-server` using WebSocket communication.
22

23
```javascript { .api }
24
// sockets/WDSSocket.js
25
const WDSSocket = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WDSSocket');
26
```
27

28
**Configuration:**
29
```javascript
30
new ReactRefreshPlugin({
31
  overlay: {
32
    sockIntegration: 'wds' // Default
33
  }
34
});
35
```
36

37
**Requirements:**
38
- `webpack-dev-server`: ^4.8.0 || 5.x
39
- WebSocket support in browser
40
- HMR enabled in webpack configuration
41

42
**Features:**
43
- Real-time compilation status updates
44
- Hot Module Replacement coordination
45
- Error message broadcasting
46
- Connection status monitoring
47

48
**Usage Example:**
49
```javascript
50
// webpack.config.js
51
const path = require('path');
52
const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
53

54
module.exports = {
55
  mode: 'development',
56
  devServer: {
57
    hot: true,
58
    port: 3000
59
  },
60
  plugins: [
61
    new ReactRefreshPlugin({
62
      overlay: {
63
        sockIntegration: 'wds'
64
      }
65
    })
66
  ]
67
};
68
```
69

70
### Webpack Hot Middleware Integration (WHM)
71

72
Integration for `webpack-hot-middleware` using EventSource/Server-Sent Events.
73

74
```javascript { .api }
75
// sockets/WHMEventSource.js
76
const WHMEventSource = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WHMEventSource');
77
```
78

79
**Configuration:**
80
```javascript
81
new ReactRefreshPlugin({
82
  overlay: {
83
    sockIntegration: 'whm'
84
  }
85
});
86
```
87

88
**Requirements:**
89
- `webpack-hot-middleware`: 2.x
90
- Express or compatible server
91
- EventSource support in browser
92

93
**Features:**
94
- Server-sent events for compilation updates
95
- Express middleware integration
96
- Custom endpoint configuration
97
- Automatic reconnection handling
98

99
**Usage Example:**
100
```javascript
101
// server.js
102
const express = require('express');
103
const webpack = require('webpack');
104
const webpackHotMiddleware = require('webpack-hot-middleware');
105
const config = require('./webpack.config.js');
106

107
const app = express();
108
const compiler = webpack(config);
109

110
app.use(webpackHotMiddleware(compiler, {
111
  path: '/__webpack_hmr',
112
  heartbeat: 10 * 1000
113
}));
114

115
// webpack.config.js
116
module.exports = {
117
  entry: [
118
    'webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000',
119
    './src/index.js'
120
  ],
121
  plugins: [
122
    new ReactRefreshPlugin({
123
      overlay: {
124
        sockIntegration: 'whm'
125
      }
126
    })
127
  ]
128
};
129
```
130

131
### Webpack Plugin Serve Integration (WPS)
132

133
Integration for `webpack-plugin-serve` using WebSocket communication.
134

135
```javascript { .api }
136
// sockets/WPSSocket.js
137
const WPSSocket = require('@pmmmwh/react-refresh-webpack-plugin/sockets/WPSSocket');
138
```
139

140
**Configuration:**
141
```javascript
142
new ReactRefreshPlugin({
143
  overlay: {
144
    sockIntegration: 'wps'
145
  }
146
});
147
```
148

149
**Requirements:**
150
- `webpack-plugin-serve`: 1.x
151
- WebSocket support in browser
152
- Plugin configured in webpack setup
153

154
**Features:**
155
- WebSocket-based communication
156
- Build status notifications
157
- Error and warning broadcasting
158
- Development server coordination
159

160
**Usage Example:**
161
```javascript
162
// webpack.config.js
163
const { WebpackPluginServe } = require('webpack-plugin-serve');
164
const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
165

166
module.exports = {
167
  entry: ['webpack-plugin-serve/client', './src/index.js'],
168
  plugins: [
169
    new ReactRefreshPlugin({
170
      overlay: {
171
        sockIntegration: 'wps'
172
      }
173
    }),
174
    new WebpackPluginServe({
175
      port: 3000,
176
      static: './dist'
177
    })
178
  ]
179
};
180
```
181

182
### Custom Socket Integration
183

184
Create custom integrations for other development servers or custom setups.
185

186
```javascript { .api }
187
// Socket integration modules export an init function
188
interface SocketIntegrationModule {
189
  init(messageHandler: (message: HMRMessage) => void): void;
190
}
191

192
// All built-in socket integrations follow this pattern:
193
function initWDSSocket(messageHandler: (message: HMRMessage) => void): void;
194
function initWHMEventSource(messageHandler: (message: HMRMessage) => void): void;
195
function initWPSSocket(messageHandler: (message: HMRMessage) => void): void;
196
```
197

198
**Custom Integration Example:**
199
```javascript
200
// custom-socket.js
201
let socket = null;
202
let messageHandlers = [];
203
let errorHandlers = [];
204
let closeHandlers = [];
205

206
function connect() {
207
  socket = new WebSocket('ws://localhost:8080/hmr');
208
  
209
  socket.onmessage = (event) => {
210
    const data = JSON.parse(event.data);
211
    messageHandlers.forEach(handler => handler(data));
212
  };
213
  
214
  socket.onerror = (error) => {
215
    errorHandlers.forEach(handler => handler(error));
216
  };
217
  
218
  socket.onclose = () => {
219
    closeHandlers.forEach(handler => handler());
220
  };
221
}
222

223
function disconnect() {
224
  if (socket) {
225
    socket.close();
226
    socket = null;
227
  }
228
}
229

230
function onMessage(callback) {
231
  messageHandlers.push(callback);
232
}
233

234
function onError(callback) {
235
  errorHandlers.push(callback);
236
}
237

238
function onClose(callback) {
239
  closeHandlers.push(callback);
240
}
241

242
module.exports = {
243
  connect,
244
  disconnect,
245
  onMessage,
246
  onError,
247
  onClose
248
};
249
```
250

251
**Using Custom Integration:**
252
```javascript
253
new ReactRefreshPlugin({
254
  overlay: {
255
    sockIntegration: './src/custom-socket.js'
256
  }
257
});
258
```
259

260
### Socket Message Protocol
261

262
Standard message format for communication between server and client:
263

264
```javascript { .api }
265
interface HMRMessage {
266
  type: 'ok' | 'warnings' | 'errors' | 'hash' | 'still-ok' | 'invalid';
267
  data?: any;
268
  hash?: string;
269
  warnings?: string[];
270
  errors?: string[];
271
}
272
```
273

274
**Message Types:**
275
- **ok**: Compilation successful, no errors or warnings
276
- **warnings**: Compilation successful with warnings
277
- **errors**: Compilation failed with errors
278
- **hash**: New compilation hash available
279
- **still-ok**: Compilation still valid (no changes)
280
- **invalid**: Compilation invalidated, rebuild starting
281

282
**Example Messages:**
283
```javascript
284
// Successful compilation
285
{
286
  type: 'ok',
287
  hash: 'abc123def456'
288
}
289

290
// Compilation with errors
291
{
292
  type: 'errors',
293
  errors: [
294
    'Module not found: Error: Can\'t resolve \'./missing-file\'',
295
    'SyntaxError: Unexpected token'
296
  ]
297
}
298

299
// Compilation with warnings
300
{
301
  type: 'warnings',
302
  warnings: [
303
    'Warning: React Hook useEffect has a missing dependency'
304
  ]
305
}
306
```
307

308
### Connection Management
309

310
All socket integrations provide connection lifecycle management:
311

312
**Connection States:**
313
- **connecting**: Establishing connection to server
314
- **connected**: Successfully connected and receiving messages
315
- **disconnected**: Connection lost or explicitly closed
316
- **error**: Connection error occurred
317

318
**Automatic Reconnection:**
319
```javascript
320
// Built-in reconnection logic
321
function attemptReconnection() {
322
  let attempts = 0;
323
  const maxAttempts = 10;
324
  const baseDelay = 1000;
325
  
326
  function reconnect() {
327
    if (attempts >= maxAttempts) {
328
      console.error('Max reconnection attempts reached');
329
      return;
330
    }
331
    
332
    attempts++;
333
    const delay = baseDelay * Math.pow(2, attempts - 1);
334
    
335
    setTimeout(() => {
336
      try {
337
        connect();
338
      } catch (error) {
339
        console.warn('Reconnection failed, retrying...', error);
340
        reconnect();
341
      }
342
    }, delay);
343
  }
344
  
345
  reconnect();
346
}
347
```
348

349
### Integration Selection
350

351
The plugin automatically selects the appropriate integration based on configuration:
352

353
```javascript
354
// Integration resolution logic
355
function resolveSocketIntegration(sockIntegration) {
356
  switch (sockIntegration) {
357
    case 'wds':
358
      return require.resolve('./sockets/WDSSocket');
359
    case 'whm':
360
      return require.resolve('./sockets/WHMEventSource');
361
    case 'wps':
362
      return require.resolve('./sockets/WPSSocket');
363
    case false:
364
      return false;
365
    default:
366
      // Custom integration path
367
      return require.resolve(sockIntegration);
368
  }
369
}
370
```
371

372
### Disabling Socket Integration
373

374
Disable socket communication when using custom error handling:
375

376
```javascript
377
new ReactRefreshPlugin({
378
  overlay: {
379
    sockIntegration: false
380
  }
381
});
382
```
383

384
When disabled:
385
- No client-server communication established
386
- Error overlay won't receive compilation updates
387
- Manual error handling required
388
- HMR coordination must be handled separately