0
# Plugin Configuration
1

2
Comprehensive configuration options for the ReactRefreshPlugin to customize Fast Refresh behavior and integration.
3

4
## Capabilities
5

6
### ReactRefreshPlugin Constructor
7

8
Creates a new instance of the React Refresh Plugin with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * @param {ReactRefreshPluginOptions} [options] Options for react-refresh-plugin.
13
 */
14
constructor(options?: ReactRefreshPluginOptions);
15
```
16

17
**Usage Example:**
18

19
```javascript
20
const ReactRefreshPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
21

22
const plugin = new ReactRefreshPlugin({
23
  exclude: /node_modules/,
24
  include: /\.[jt]sx?$/,
25
  forceEnable: false,
26
  overlay: {
27
    sockIntegration: 'wds'
28
  }
29
});
30
```
31

32
### Apply Method
33

34
Applies the plugin to a Webpack compiler instance.
35

36
```javascript { .api }
37
/**
38
 * Applies the plugin.
39
 * @param {import('webpack').Compiler} compiler A webpack compiler object.
40
 * @returns {void}
41
 */
42
apply(compiler: import('webpack').Compiler): void;
43
```
44

45
**Usage Example:**
46

47
```javascript
48
// Automatically called by Webpack when plugin is added to plugins array
49
module.exports = {
50
  plugins: [
51
    new ReactRefreshPlugin(options)
52
  ]
53
};
54
```
55

56
### Plugin Options
57

58
Main configuration interface for customizing plugin behavior.
59

60
```javascript { .api }
61
interface ReactRefreshPluginOptions {
62
  /**
63
   * Enables strict ES Modules compatible runtime.
64
   */
65
  esModule?: boolean | ESModuleOptions;
66
  
67
  /**
68
   * Files to explicitly exclude from processing.
69
   */
70
  exclude?: string | RegExp | (string | RegExp)[];
71
  
72
  /**
73
   * Enables the plugin forcefully.
74
   */
75
  forceEnable?: boolean;
76
  
77
  /**
78
   * Files to explicitly include for processing.
79
   */
80
  include?: string | RegExp | (string | RegExp)[];
81
  
82
  /**
83
   * Name of the library bundle.
84
   */
85
  library?: string;
86
  
87
  /**
88
   * Modifies how the error overlay integration works in the plugin.
89
   */
90
  overlay?: boolean | ErrorOverlayOptions;
91
}
92
```
93

94
### Force Enable Option
95

96
Enables the plugin forcefully, bypassing normal development mode checks.
97

98
```javascript { .api }
99
forceEnable?: boolean;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
// Enable in production (not recommended)
106
new ReactRefreshPlugin({
107
  forceEnable: true
108
});
109

110
// Enable with 'none' mode without NODE_ENV
111
new ReactRefreshPlugin({
112
  forceEnable: process.env.WEBPACK_MODE !== 'production'
113
});
114
```
115

116
**Default:** `undefined`
117

118
**Use Cases:**
119
- Production usage (proceed at your own risk)
120
- Usage with `none` mode in Webpack without setting `NODE_ENV`
121
- Usage in unsupported environments like `electron-prerender`
122

123
### Include/Exclude Options
124

125
Control which files are processed by the plugin using patterns similar to Webpack's `module.rules`.
126

127
```javascript { .api }
128
exclude?: string | RegExp | (string | RegExp)[];
129
include?: string | RegExp | (string | RegExp)[];
130
```
131

132
**Usage Examples:**
133

134
```javascript
135
// Exclude node_modules and specific directories
136
new ReactRefreshPlugin({
137
  exclude: [/node_modules/, /\.spec\.[jt]sx?$/]
138
});
139

140
// Include only specific file patterns
141
new ReactRefreshPlugin({
142
  include: /src\/.*\.[jt]sx?$/
143
});
144

145
// Multiple patterns
146
new ReactRefreshPlugin({
147
  exclude: [
148
    /node_modules/,
149
    /build/,
150
    path.resolve(__dirname, 'vendor')
151
  ]
152
});
153
```
154

155
**Defaults:**
156
- `exclude`: `/node_modules/`
157
- `include`: `/\.([jt]sx?|flow)$/i`
158

159
### Library Option
160

161
Sets a namespace for the React Refresh runtime, useful when multiple instances run simultaneously.
162

163
```javascript { .api }
164
library?: string;
165
```
166

167
**Usage Examples:**
168

169
```javascript
170
// Set custom library namespace
171
new ReactRefreshPlugin({
172
  library: 'MyApp'
173
});
174

175
// Use webpack output configuration
176
module.exports = {
177
  output: {
178
    library: 'MyLibrary'
179
  },
180
  plugins: [
181
    new ReactRefreshPlugin() // Will use 'MyLibrary'
182
  ]
183
};
184
```
185

186
**Default:** `''`, or `output.uniqueName` in Webpack 5, or `output.library` if set
187

188
### ES Module Options
189

190
Controls ES Modules compatibility for the refresh runtime.
191

192
```javascript { .api }
193
esModule?: boolean | ESModuleOptions;
194

195
interface ESModuleOptions {
196
  /**
197
   * Files to explicitly exclude from flagged as ES Modules.
198
   */
199
  exclude?: string | RegExp | (string | RegExp)[];
200
  
201
  /**
202
   * Files to explicitly include for flagged as ES Modules.
203
   */
204
  include?: string | RegExp | (string | RegExp)[];
205
}
206
```
207

208
**Usage Examples:**
209

210
```javascript
211
// Enable ES Modules globally
212
new ReactRefreshPlugin({
213
  esModule: true
214
});
215

216
// Granular ES Module control
217
new ReactRefreshPlugin({
218
  esModule: {
219
    include: /src\/.*\.m[jt]s$/,
220
    exclude: /legacy/
221
  }
222
});
223

224
// Auto-detection (default)
225
new ReactRefreshPlugin({
226
  esModule: undefined // Plugin will infer from package.json type or file extension
227
});
228
```
229

230
**Default:** `undefined` (auto-detection based on `package.json` type field or file extensions `.mjs`/`.cjs`)
231

232
### Normalized Plugin Options
233

234
Internal interface representing processed plugin options after normalization.
235

236
```javascript { .api }
237
interface NormalizedPluginOptions {
238
  esModule?: boolean | ESModuleOptions;
239
  exclude: string | RegExp | (string | RegExp)[];
240
  include: string | RegExp | (string | RegExp)[];
241
  forceEnable?: boolean;
242
  library?: string;
243
  overlay: false | NormalizedErrorOverlayOptions;
244
}
245
```
246

247
### Options Validation
248

249
The plugin uses JSON schema validation to ensure correct configuration.
250

251
**Schema Location:** `lib/options.json`
252

253
**Validation Features:**
254
- Type checking for all options
255
- Pattern validation for file matching
256
- Enum validation for overlay socket integration types
257
- Additional properties prevention
258

259
**Error Handling:**
260
```javascript
261
// Invalid configuration will throw during plugin instantiation
262
try {
263
  new ReactRefreshPlugin({
264
    invalidOption: true // Will throw validation error
265
  });
266
} catch (error) {
267
  console.error('Plugin configuration error:', error.message);
268
}
269
```