0
# @rsbuild/plugin-react  
1

2
@rsbuild/plugin-react provides comprehensive React support for Rsbuild, including JSX compilation, React Fast Refresh for hot reloading during development, and React Profiler integration for performance analysis. The plugin offers configurable chunk splitting for React-related dependencies and seamless integration with Rsbuild's build pipeline.
3

4
## Package Information
5

6
- **Package Name**: @rsbuild/plugin-react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @rsbuild/plugin-react --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { pluginReact } from "@rsbuild/plugin-react";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { pluginReact } = require("@rsbuild/plugin-react");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { defineConfig } from "@rsbuild/core";
27
import { pluginReact } from "@rsbuild/plugin-react";
28

29
export default defineConfig({
30
  plugins: [pluginReact()],
31
});
32
```
33

34
With configuration options:
35

36
```typescript
37
import { defineConfig } from "@rsbuild/core";
38
import { pluginReact } from "@rsbuild/plugin-react";
39

40
export default defineConfig({
41
  plugins: [
42
    pluginReact({
43
      fastRefresh: true,
44
      enableProfiler: false,
45
      splitChunks: {
46
        react: true,
47
        router: true,
48
      },
49
      swcReactOptions: {
50
        runtime: "automatic",
51
        development: true,
52
      },
53
    }),
54
  ],
55
});
56
```
57

58
## Capabilities
59

60
### Plugin Factory Function
61

62
Creates a React plugin instance for Rsbuild with customizable options.
63

64
```typescript { .api }
65
/**
66
 * Creates a React plugin for Rsbuild
67
 * @param options - Optional configuration for React support
68
 * @returns RsbuildPlugin instance
69
 */
70
function pluginReact(options?: PluginReactOptions): RsbuildPlugin;
71
```
72

73
### Configuration Options
74

75
Complete configuration interface for customizing React support.
76

77
```typescript { .api }
78
interface PluginReactOptions {
79
  /**
80
   * Configure the behavior of SWC to transform React code,
81
   * the same as SWC's jsc.transform.react configuration
82
   */
83
  swcReactOptions?: Rspack.SwcLoaderTransformConfig["react"];
84

85
  /**
86
   * Configuration for chunk splitting of React-related dependencies
87
   */
88
  splitChunks?: SplitReactChunkOptions;
89

90
  /**
91
   * When set to true, enables the React Profiler for performance analysis in production builds
92
   * @default false
93
   */
94
  enableProfiler?: boolean;
95

96
  /**
97
   * Options passed to @rspack/plugin-react-refresh
98
   * @default { include: [/\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts)$/], exclude: [/[\\/]node_modules[\\/]/], resourceQuery: { not: /raw/ } }
99
   */
100
  reactRefreshOptions?: ReactRefreshOptions;
101

102
  /**
103
   * Whether to enable React Fast Refresh in development mode
104
   * @default true
105
   */
106
  fastRefresh?: boolean;
107
}
108
```
109

110
### Chunk Splitting Configuration
111

112
Configuration for splitting React and routing dependencies into separate chunks.
113

114
```typescript { .api }
115
interface SplitReactChunkOptions {
116
  /**
117
   * Whether to enable split chunking for React-related dependencies (e.g., react, react-dom, scheduler)
118
   * @default true
119
   */
120
  react?: boolean;
121

122
  /**
123
   * Whether to enable split chunking for routing-related dependencies (e.g., react-router, react-router-dom, history)
124
   * @default true
125
   */
126
  router?: boolean;
127
}
128
```
129

130
### Plugin Identifier
131

132
Constant identifier for the React plugin.
133

134
```typescript { .api }
135
/**
136
 * Identifier for the React plugin
137
 */
138
const PLUGIN_REACT_NAME = "rsbuild:react";
139
```
140

141
## Types
142

143
### External Type References
144

145
The plugin uses types from external packages that are available when using Rsbuild:
146

147
```typescript { .api }
148
// From @rsbuild/core
149
interface RsbuildPlugin {
150
  name: string;
151
  setup(api: RsbuildPluginAPI): void;
152
}
153

154
// From @rspack/plugin-react-refresh (imported as ReactRefreshOptions)
155
interface ReactRefreshOptions {
156
  include?: RegExp[];
157
  exclude?: RegExp[];
158
  resourceQuery?: { not: RegExp };
159
}
160

161
// From @rsbuild/core (Rspack configuration)
162
interface SwcLoaderTransformConfig {
163
  react?: {
164
    development?: boolean;
165
    refresh?: boolean;
166
    runtime?: "automatic" | "classic";
167
    importSource?: string;
168
  };
169
}
170
```
171

172
## Usage Examples
173

174
### Basic React App Setup
175

176
```typescript
177
import { defineConfig } from "@rsbuild/core";
178
import { pluginReact } from "@rsbuild/plugin-react";
179

180
export default defineConfig({
181
  plugins: [pluginReact()],
182
  html: {
183
    template: "./src/index.html",
184
  },
185
  source: {
186
    entry: {
187
      index: "./src/index.tsx",
188
    },
189
  },
190
});
191
```
192

193
### Development with Custom Fast Refresh Options
194

195
```typescript
196
import { defineConfig } from "@rsbuild/core";
197
import { pluginReact } from "@rsbuild/plugin-react";
198

199
export default defineConfig({
200
  plugins: [
201
    pluginReact({
202
      fastRefresh: true,
203
      reactRefreshOptions: {
204
        include: [/\.tsx?$/],
205
        exclude: [/node_modules/, /\.stories\./],
206
      },
207
    }),
208
  ],
209
});
210
```
211

212
### Production with Profiler Enabled
213

214
```typescript
215
import { defineConfig } from "@rsbuild/core";
216
import { pluginReact } from "@rsbuild/plugin-react";
217

218
export default defineConfig({
219
  plugins: [
220
    pluginReact({
221
      enableProfiler: process.env.NODE_ENV === "production",
222
      splitChunks: {
223
        react: true,
224
        router: false, // Disable router splitting if not needed
225
      },
226
    }),
227
  ],
228
});
229
```
230

231
### Custom SWC React Configuration
232

233
```typescript
234
import { defineConfig } from "@rsbuild/core";
235
import { pluginReact } from "@rsbuild/plugin-react";
236

237
export default defineConfig({
238
  plugins: [
239
    pluginReact({
240
      swcReactOptions: {
241
        runtime: "classic", // Use classic JSX runtime
242
        importSource: "@emotion/react", // Custom JSX import source
243
        development: false, // Force production mode
244
      },
245
    }),
246
  ],
247
});
248
```
249

250
### Disabling Chunk Splitting
251

252
```typescript
253
import { defineConfig } from "@rsbuild/core";
254
import { pluginReact } from "@rsbuild/plugin-react";
255

256
export default defineConfig({
257
  plugins: [
258
    pluginReact({
259
      splitChunks: {
260
        react: false,
261
        router: false,
262
      },
263
    }),
264
  ],
265
});
266
```
267

268
## Environment-Specific Configuration
269

270
The plugin can be applied to specific environments in multi-environment builds:
271

272
```typescript
273
import { defineConfig } from "@rsbuild/core";
274
import { pluginReact } from "@rsbuild/plugin-react";
275

276
export default defineConfig({
277
  environments: {
278
    web: {
279
      plugins: [
280
        pluginReact({
281
          fastRefresh: true,
282
          enableProfiler: false,
283
        }),
284
      ],
285
      output: {
286
        target: "web",
287
      },
288
    },
289
    node: {
290
      // React plugin not needed for Node.js builds
291
      output: {
292
        target: "node",
293
      },
294
    },
295
  },
296
});
297
```
298

299
## Key Features
300

301
- **JSX/TSX Compilation**: Automatic JSX and TSX file processing via SWC transformer
302
- **React Fast Refresh**: Hot reloading with state preservation during development
303
- **React Profiler**: Production profiling support with optimized minification settings
304
- **Intelligent Chunk Splitting**: Separates React and routing dependencies for optimal loading
305
- **TypeScript Support**: Full TypeScript integration with proper syntax parsing
306
- **Flexible Configuration**: Comprehensive options for customizing React support behavior
307
- **Environment Awareness**: Automatically adjusts behavior based on development/production mode
308
- **HMR Integration**: Seamless integration with Rsbuild's Hot Module Replacement system