Guide
Config
Plugin
API
Guide
Config
Plugin
API

Create React App

This chapter introduces how to migrate a Create React App (CRA) project to Rsbuild.

Installing Dependencies

First, you need to replace the npm dependencies of CRA with Rsbuild's dependencies.

Remove CRA dependencies:

npm
yarn
pnpm
bun
npm remove react-scripts

Install Rsbuild dependencies:

npm
yarn
pnpm
bun
npm add @rsbuild/core @rsbuild/plugin-react -D

Updating npm scripts

Next, you need to update the npm scripts in package.json to Rsbuild's CLI commands.

package.json
{
  "scripts": {
-   "start": "react-scripts start",
-   "build": "react-scripts build",
-   "eject": "react-scripts eject"
+   "start": "rsbuild dev",
+   "build": "rsbuild build",
+   "preview": "rsbuild preview"
  }
}
TIP

Rsbuild does not integrate testing frameworks, so it does not provide a command to replace react-scripts test. You can directly use testing frameworks such as Jest or Vitest.

Creating Configuration File

Create a Rsbuild configuration file rsbuild.config.ts in the same directory as package.json and add the following content:

rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  plugins: [pluginReact()],
});

This completes the basic migration from CRA to Rsbuild. You can now run the npm run start command to try starting the dev server.

Using SVGR

If you are using the "SVG to React Component" feature of CRA (i.e., SVGR), you also need to install the SVGR plugin for Rsbuild.

For example, if you are using the following usage:

import { ReactComponent as Logo } from './logo.svg';

const App = () => (
  <div>
    <Logo />
  </div>
);

Please refer to the SVGR plugin documentation to learn how to use SVGR in Rsbuild.

Configuration Migration

Here is the corresponding Rsbuild configuration for CRA configuration:

CRA Rsbuild
HOST server.host
PORT server.port
HTTPS server.https
WDS_SOCKET_HOST dev.client.host
WDS_SOCKET_PATH dev.client.path
WDS_SOCKET_PORT dev.client.port
PUBLIC_URL dev.assetPrefix / output.assetPrefix
BUILD_PATH output.distPath
GENERATE_SOURCEMAP output.sourceMap
IMAGE_INLINE_SIZE_LIMIT output.dataUriLimit
FAST_REFRESH dev.hmr
TSC_COMPILE_ON_ERROR Type Check Plugin

Notes:

  • The above table does not cover all configurations of CRA, feel free to add more.

Compile node_modules

By default, CRA uses Babel to compile dependencies in node_modules, but Rsbuild does not, to avoid the performance overhead and potential compilation errors caused by secondary compilation.

If you need to handle syntax compatibility issues caused by dependencies in node_modules, you can use the [source.include](

Environment Variables

CRA injects environment variables starting with REACT_APP_ into the client code by default, while Rsbuild injects environment variables starting with PUBLIC_ by default (see public variables).

To be compatible with CRA's behavior, you can manually call Rsbuild's loadEnv method to read environment variables starting with REACT_APP_, and inject them into the client code through the source.define config.

rsbuild.config.ts
import { defineConfig, loadEnv } from '@rsbuild/core';

const { publicVars } = loadEnv({ prefixes: ['REACT_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});

Contents Supplement

The current document only covers part of the migration process. If you find suitable content to add, feel free to contribute to the documentation via pull request 🤝.

The documentation for rsbuild can be found in the rsbuild/packages/document directory.