0
# Webpack Plugin
1
2
Webpack plugin for processing React Server Components, automatically detecting client references with "use client" directives, and generating client and server manifests for module resolution.
3
4
## Capabilities
5
6
### ReactFlightWebpackPlugin
7
8
Main webpack plugin class that integrates React Server Components processing into the webpack build pipeline.
9
10
```javascript { .api }
11
/**
12
* Webpack plugin for React Server Components processing
13
* @param options - Plugin configuration options
14
*/
15
class ReactFlightWebpackPlugin {
16
constructor(options: PluginOptions);
17
18
/**
19
* Applies the plugin to the webpack compiler
20
* @param compiler - Webpack compiler instance
21
*/
22
apply(compiler: WebpackCompiler): void;
23
}
24
```
25
26
**Usage Example:**
27
28
```javascript
29
const ReactFlightWebpackPlugin = require("react-server-dom-webpack/plugin");
30
31
module.exports = {
32
plugins: [
33
new ReactFlightWebpackPlugin({
34
isServer: false,
35
clientReferences: [
36
{
37
directory: "./src/components",
38
recursive: true,
39
include: /\.(js|jsx|ts|tsx)$/,
40
exclude: /\.test\./
41
},
42
"./src/pages/**/*.client.js"
43
],
44
chunkName: "client-[index]",
45
clientManifestFilename: "client-manifest.json",
46
serverConsumerManifestFilename: "server-manifest.json"
47
})
48
]
49
};
50
```
51
52
### Plugin Configuration
53
54
The plugin accepts comprehensive configuration options for customizing client reference detection and manifest generation.
55
56
```javascript { .api }
57
interface PluginOptions {
58
/** Whether this is a server-side build (currently must be false) */
59
isServer: boolean;
60
/** Client reference paths or search configurations */
61
clientReferences?: ClientReferencePath | ClientReferencePath[];
62
/** Chunk naming pattern for client references */
63
chunkName?: string;
64
/** Output filename for client manifest */
65
clientManifestFilename?: string;
66
/** Output filename for server consumer manifest */
67
serverConsumerManifestFilename?: string;
68
}
69
70
type ClientReferencePath = string | ClientReferenceSearchPath;
71
72
interface ClientReferenceSearchPath {
73
/** Directory to search for client references */
74
directory: string;
75
/** Whether to search recursively in subdirectories */
76
recursive?: boolean;
77
/** RegExp pattern for files to include */
78
include: RegExp;
79
/** RegExp pattern for files to exclude */
80
exclude?: RegExp;
81
}
82
```
83
84
**Configuration Examples:**
85
86
```javascript
87
// Simple string-based client references
88
{
89
isServer: false,
90
clientReferences: [
91
"./src/components/Button.tsx",
92
"./src/components/Modal.tsx"
93
]
94
}
95
96
// Directory-based search configuration
97
{
98
isServer: false,
99
clientReferences: [
100
{
101
directory: "./src",
102
recursive: true,
103
include: /\.(js|jsx|ts|tsx)$/,
104
exclude: /\.(test|spec)\./
105
}
106
]
107
}
108
109
// Mixed configuration
110
{
111
isServer: false,
112
clientReferences: [
113
"./src/components/SpecialComponent.tsx",
114
{
115
directory: "./src/pages",
116
recursive: true,
117
include: /\.client\.(js|tsx)$/
118
}
119
]
120
}
121
```
122
123
### Client Reference Detection
124
125
The plugin automatically detects files with "use client" directive and processes them for client-side code splitting.
126
127
**Client Component Example:**
128
129
```javascript
130
// src/components/Button.tsx
131
"use client";
132
133
import { useState } from "react";
134
135
export function Button({ children, onClick }) {
136
const [loading, setLoading] = useState(false);
137
138
return (
139
<button
140
onClick={async () => {
141
setLoading(true);
142
await onClick();
143
setLoading(false);
144
}}
145
disabled={loading}
146
>
147
{loading ? "Loading..." : children}
148
</button>
149
);
150
}
151
```
152
153
### Manifest Generation
154
155
The plugin generates two key manifest files for runtime module resolution:
156
157
#### Client Manifest
158
159
Maps client components to their webpack chunks for dynamic loading.
160
161
```json
162
{
163
"file:///path/to/Button.tsx": {
164
"id": "./src/components/Button.tsx",
165
"chunks": ["client-0", "client-0.js"],
166
"name": "*"
167
}
168
}
169
```
170
171
#### Server Consumer Manifest
172
173
Provides server-side module loading configuration and mappings.
174
175
```json
176
{
177
"moduleLoading": {
178
"prefix": "/static/js/",
179
"crossOrigin": "anonymous"
180
},
181
"moduleMap": {
182
"./src/components/Button.tsx": {
183
"*": {
184
"specifier": "file:///path/to/Button.tsx",
185
"name": "*"
186
}
187
}
188
}
189
}
190
```
191
192
### Chunk Naming
193
194
Customizable chunk naming patterns for client reference bundles.
195
196
```javascript { .api }
197
// Default chunk naming
198
chunkName: "client[index]"
199
200
// Custom naming with request path
201
chunkName: "rsc-[request]-[index]"
202
203
// Results in chunks like: rsc-Button-0.js, rsc-Modal-1.js
204
```
205
206
**Chunk Naming Patterns:**
207
208
- `[index]` - Sequential index number for each client reference
209
- `[request]` - Transformed request path of the client component
210
- Custom prefix/suffix - Any static string to identify RSC chunks
211
212
### Error Handling and Warnings
213
214
The plugin provides detailed error reporting and warnings for common configuration issues.
215
216
**Common Warnings:**
217
218
```javascript
219
// Warning when client runtime is not found
220
"Client runtime at react-server-dom-webpack/client was not found.
221
React Server Components module map file client-manifest.json was not created."
222
223
// Error for invalid server configuration
224
"React Server Plugin: You must specify the isServer option as a boolean."
225
226
// Error for unsupported server mode
227
"TODO: Implement the server compiler."
228
```
229
230
### Advanced Configuration
231
232
Additional configuration options for fine-tuning plugin behavior.
233
234
```javascript { .api }
235
// Advanced webpack.config.js setup
236
module.exports = {
237
plugins: [
238
new ReactFlightWebpackPlugin({
239
isServer: false,
240
clientReferences: [
241
{
242
directory: "./src",
243
recursive: true,
244
include: /\.(js|jsx|ts|tsx)$/,
245
exclude: /\.(test|spec|d\.ts)$/
246
}
247
],
248
chunkName: "rsc-[request]-[index]",
249
clientManifestFilename: "rsc-client-manifest.json",
250
serverConsumerManifestFilename: "rsc-server-manifest.json"
251
})
252
],
253
output: {
254
crossOriginLoading: "anonymous", // Affects manifest crossOrigin setting
255
publicPath: "/assets/" // Affects manifest prefix setting
256
}
257
};
258
```
259
260
## Integration Notes
261
262
### Build Pipeline Integration
263
264
The plugin integrates deeply with webpack's compilation process:
265
266
1. **Module Analysis**: Scans specified directories for client references
267
2. **Directive Processing**: Parses files using acorn to detect "use client"
268
3. **Dependency Injection**: Adds client references as async dependencies
269
4. **Chunk Generation**: Creates separate chunks for client components
270
5. **Manifest Creation**: Generates runtime manifests during asset processing
271
272
### Runtime Requirements
273
274
The plugin requires the React Server DOM client runtime to be imported somewhere in the build to establish the dependency graph:
275
276
```javascript
277
// This import must exist in your client bundle
278
import "react-server-dom-webpack/client";
279
```
280
281
### Multi-Environment Builds
282
283
For applications supporting multiple environments, configure separate webpack builds:
284
285
```javascript
286
// webpack.client.js
287
module.exports = {
288
entry: "./src/client.js",
289
plugins: [
290
new ReactFlightWebpackPlugin({
291
isServer: false,
292
clientReferences: [/* client refs */]
293
})
294
]
295
};
296
297
// webpack.server.js
298
module.exports = {
299
entry: "./src/server.js",
300
target: "node",
301
// Server builds currently use external manifest consumption
302
externals: {
303
"react-server-dom-webpack/client": "commonjs2 react-server-dom-webpack/client"
304
}
305
};
306
```