0
# Plugin Utilities
1

2
Core utility functions for advanced plugin integration and customization, providing low-level access to the plugin's internal mechanisms.
3

4
## Capabilities
5

6
### Get Additional Entries
7

8
Retrieves additional entry points required for React Refresh integration.
9

10
```javascript { .api }
11
/**
12
 * Gets additional webpack entries for React Refresh integration
13
 * @param {NormalizedPluginOptions} options - Normalized plugin options
14
 * @returns {{ overlayEntries: string[], prependEntries: string[] }}
15
 */
16
function getAdditionalEntries(options: NormalizedPluginOptions): {
17
  overlayEntries: string[];
18
  prependEntries: string[];
19
};
20
```
21

22
**Usage Example:**
23

24
```javascript
25
const { getAdditionalEntries } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
26

27
// Get entries for custom webpack configuration
28
const { overlayEntries, prependEntries } = getAdditionalEntries({
29
  overlay: {
30
    entry: '@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry',
31
    module: '@pmmmwh/react-refresh-webpack-plugin/overlay',
32
    sockIntegration: 'wds'
33
  }
34
});
35

36
console.log('Overlay entries:', overlayEntries);
37
console.log('Prepend entries:', prependEntries);
38
```
39

40
### Get Integration Entry
41

42
Resolves the integration entry point path for a given socket integration type.
43

44
```javascript { .api }
45
/**
46
 * Gets the integration entry path for socket communication
47
 * @param {string | false} sockIntegration - Socket integration identifier
48
 * @returns {string} - Path to integration entry module
49
 */
50
function getIntegrationEntry(sockIntegration: string | false): string;
51
```
52

53
**Usage Example:**
54

55
```javascript
56
const { getIntegrationEntry } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
57

58
// Get webpack-dev-server integration entry
59
const wdsEntry = getIntegrationEntry('wds');
60
console.log('WDS integration entry:', wdsEntry);
61

62
// Get custom integration entry
63
const customEntry = getIntegrationEntry('./custom-integration.js');
64
console.log('Custom integration entry:', customEntry);
65
```
66

67
### Get Socket Integration
68

69
Resolves the socket integration module path for client-server communication.
70

71
```javascript { .api }
72
/**
73
 * Gets the socket integration module path
74
 * @param {string | false} sockIntegration - Socket integration identifier
75
 * @returns {string | false} - Path to socket integration module or false if disabled
76
 */
77
function getSocketIntegration(sockIntegration: string | false): string | false;
78
```
79

80
**Usage Example:**
81

82
```javascript
83
const { getSocketIntegration } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
84

85
// Get built-in socket integrations
86
const wdsSocket = getSocketIntegration('wds');
87
const whmSocket = getSocketIntegration('whm');  
88
const wpsSocket = getSocketIntegration('wps');
89

90
console.log('Socket modules:', { wdsSocket, whmSocket, wpsSocket });
91

92
// Disabled integration returns false
93
const disabled = getSocketIntegration(false);
94
console.log('Disabled integration:', disabled); // false
95
```
96

97
### Inject Refresh Loader
98

99
Injects the React Refresh loader into webpack module creation data.
100

101
```javascript { .api }
102
/**
103
 * Injects React Refresh loader into webpack module data
104
 * @param {object} createData - Webpack module creation data
105
 * @param {object} config - Injection configuration
106
 * @param {Function} config.match - Function to match modules for processing
107
 * @param {object} config.options - Loader options
108
 */
109
function injectRefreshLoader(
110
  createData: any,
111
  config: {
112
    match: (filename: string) => boolean;
113
    options?: {
114
      const?: boolean;
115
      esModule?: boolean | ESModuleOptions;
116
    };
117
  }
118
): void;
119
```
120

121
**Usage Example:**
122

123
```javascript
124
const { injectRefreshLoader } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
125
const { ModuleFilenameHelpers } = require('webpack');
126

127
// Create module matcher
128
const match = ModuleFilenameHelpers.matchObject.bind(undefined, {
129
  include: /\.[jt]sx?$/,
130
  exclude: /node_modules/
131
});
132

133
// Inject loader into module creation
134
injectRefreshLoader(resolveData.createData, {
135
  match,
136
  options: {
137
    const: true,
138
    esModule: false
139
  }
140
});
141
```
142

143
### Make Refresh Runtime Module
144

145
Creates a webpack runtime module for React Refresh integration.
146

147
```javascript { .api }
148
/**
149
 * Creates a React Refresh runtime module for webpack
150
 * @param {object} webpack - Webpack instance with required utilities
151
 * @returns {Function} - RuntimeModule constructor
152
 */
153
function makeRefreshRuntimeModule(webpack: any): typeof RuntimeModule;
154
```
155

156
**Usage Example:**
157

158
```javascript
159
const { makeRefreshRuntimeModule } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
160

161
// Create runtime module class
162
const ReactRefreshRuntimeModule = makeRefreshRuntimeModule(webpack);
163

164
// Add to compilation
165
compilation.addRuntimeModule(chunk, new ReactRefreshRuntimeModule());
166
```
167

168
### Normalize Options
169

170
Normalizes and validates plugin options, setting defaults and resolving configurations.
171

172
```javascript { .api }
173
/**
174
 * Normalizes plugin options with defaults and validation
175
 * @param {ReactRefreshPluginOptions} options - Raw plugin options
176
 * @returns {NormalizedPluginOptions} - Normalized options with defaults
177
 */
178
function normalizeOptions(options: ReactRefreshPluginOptions): NormalizedPluginOptions;
179
```
180

181
**Usage Example:**
182

183
```javascript
184
const { normalizeOptions } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
185

186
// Normalize plugin options
187
const normalized = normalizeOptions({
188
  overlay: {
189
    sockIntegration: 'wds'
190
  },
191
  exclude: /node_modules/
192
});
193

194
console.log('Normalized options:', normalized);
195
// Result includes defaults for all optional properties
196
```
197

198
## Integration Patterns
199

200
### Custom Plugin Extension
201

202
Use utilities to extend the plugin with custom functionality:
203

204
```javascript
205
const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
206
const { normalizeOptions, getAdditionalEntries } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
207

208
class CustomRefreshPlugin extends ReactRefreshPlugin {
209
  constructor(options) {
210
    super(options);
211
    
212
    // Access normalized options
213
    const normalized = normalizeOptions(options);
214
    console.log('Using normalized options:', normalized);
215
    
216
    // Get additional entries for custom processing
217
    const { overlayEntries, prependEntries } = getAdditionalEntries(normalized);
218
    this.customEntries = [...overlayEntries, ...prependEntries];
219
  }
220
  
221
  apply(compiler) {
222
    // Custom pre-processing
223
    console.log('Custom entries:', this.customEntries);
224
    
225
    // Apply original plugin logic
226
    super.apply(compiler);
227
  }
228
}
229
```
230

231
### Advanced Entry Management
232

233
Manually control webpack entries using utility functions:
234

235
```javascript
236
const { getIntegrationEntry, getAdditionalEntries } = require('@pmmmwh/react-refresh-webpack-plugin/lib/utils');
237

238
// Custom webpack configuration with manual entry control
239
module.exports = {
240
  entry: {
241
    main: './src/index.js',
242
    // Add React Refresh entries manually
243
    refreshSetup: getIntegrationEntry('wds'),
244
  },
245
  
246
  plugins: [
247
    {
248
      apply(compiler) {
249
        // Get additional entries
250
        const { overlayEntries, prependEntries } = getAdditionalEntries({
251
          overlay: {
252
            entry: '@pmmmwh/react-refresh-webpack-plugin/client/ErrorOverlayEntry',
253
            module: '@pmmmwh/react-refresh-webpack-plugin/overlay',
254
            sockIntegration: 'wds'
255
          }
256
        });
257
        
258
        // Process entries as needed
259
        overlayEntries.forEach(entry => {
260
          console.log('Processing overlay entry:', entry);
261
        });
262
      }
263
    }
264
  ]
265
};
266
```