# Configure for build

To configure Rsbuild for a production environment, execute the following steps 👇

# Install the packages

pnpm add -D @workleap/rsbuild-configs @workleap/browserslist-config @rsbuild/core @rspack/core browserslist

yarn add -D @workleap/rsbuild-configs @workleap/browserslist-config @rsbuild/core @rspack/core browserslist

npm install -D @workleap/rsbuild-configs @workleap/browserslist-config @rsbuild/core @rspack/core browserslist

# Configure Rsbuild

# HTML template

First, create a public folder with an index.html file at the root of the project:

web-project
├── public
├──── index.html
├── src
├──── ...
├── package.json

Then, open the newly created index.html file and copy/paste the following content:

public/index.html
<!DOCTYPE html>
<html>
    <head>
    </head>
    <body>
        <div id="root"></div>
    </body>
</html>

The content of the public/index.html file will be the template used by Rsbuild HTML template feature.

# Reference local assets

To reference local assets such as a favicon.png in the default HTML template, it is recommended to preprend the relative path of every asset with the assetPrefix option of the Rsbuild config.

First, add the asset to the public folder at the root of the project:

web-project
├── public
├──── index.html
├──── favicon.png
├── src
├──── ...
├── package.json

Then, add the assets to the index.html file:

public/index.html
<!DOCTYPE html>
<html>
    <head>
        <link href="<%=assetPrefix%>/favicon.png" rel="icon">
    </head>
    <body>
        <div id="root"></div>
    </body>
</html>

If assetPrefix is set to auto, use href="favicon.png" instead.

# Browserslist

Next, let's set up Browserlist to define the minimum browser versions supported by the application. Rsbuild will automatically detect and load the browser versions from the nearest .browserslistrc configuration file.

First, create a browserslistrc file at the root of the project:

web-project
├── public
├──── index.html
├── src
├──── ...
├── .browserslistrc
├── package.json

Then, open the newly created file and extend the default configuration with the shared configuration provided by @workleap/browserslist-config:

.browserslistrc
extends @workleap/browserslist-config

# `rsbuild.build.ts`

Next, create a configuration file named rsbuild.build.ts at the root of the project:

web-project
├── public
├──── index.html
├── src
├──── ...
├── .browserslistrc
├── package.json
├── rsbuild.build.ts

Then, open the newly created file and export the Rsbuild configuration by using the defineBuildConfig(options) function:

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig();

# Use predefined options

The defineBuildConfig(options) function can be used as shown in the previous example, however, if you wish to customize the default configuration, the function also accept a few predefined options to help with that 👇

# `entry`

Type: RsbuildEntry
Default: { index: "./src/index.tsx" }

Set Rsbuild source.entry option.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    entry: {
        index: "./src/another-entry.tsx"
    }
});

# `distPath`

This option is the Rsbuild equivalent of webpack outputPath option.

Type: string
Default: dist

Set Rsbuild output.distPath option.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";
import path from "path";

export default defineBuildConfig({
    distPath: path.resolve("./a-custom-folder")
});

# `assetPrefix`

This option is the Rsbuild equivalent of webpack publicPath option.

Type: string
Default: ${https ? "https" : "http"}://${host}:${port}

Set Rsbuild output.assetPrefix option.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    assetPrefix: "http://dev-host:8080"
});

If you're unsure of the asset prefix in advance, set the option to auto. Rsbuild will automatically determine the asset prefix using import.meta.url or document.currentScript.

rsbuild.build.ts
import { defineBuildConfig  } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    assetPrefix: "auto"
});

# `plugins`

Type: An array of Rsbuild plugin instances
Default: []

Append the provided Rsbuild plugins to the configuration.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";
import { pluginAssetsRetry } from "@rsbuild/plugin-assets-retry";

export default defineBuildConfig({
    plugins: [pluginAssetsRetry()]
});

# `html`

Type: false or (defaultOptions: HtmlConfig) => HtmlConfig
Default: defaultOptions => defaultOptions

By default, Rsbuild will attempt to load an HTML template from the public/index.html file. To use Rsbuild's built-in HTML template instead, set the option to false.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    html: false
});

To customize the default HTML template configuration, provide a function extending the default options.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";
import path from "path";

export default defineBuildConfig({
    html: defaultOptions => {
        return {
            ...defaultOptions,
            template: path.resolve("./my-custom-index.html"),
        };
    }
});

# `minify`

Type: false or an object literal accepting any minify options.
Default: true

Whether or not to minify the code. To disable code minification, set the option to false.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    minify: false
});

To customize the minimizer configuration, provide an object literal.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    minify: {
        css: false
    }
});

# `optimize`

Type: boolean | "readable"
Default: true

Whether or not to enable Rsbuild production code optimization. This option can be quite useful when debugging an issue with Rsbuild bundling.

When false is provided, most of the optimizations, including minification will be turned off:

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    optimize: false
});

When readable is provided, most of the optimizations will still be applied but the outputed bundles will be easier to read:

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    optimize: "readable"
});

# `sourceMap`

Type: false or an object literal accepting any output.sourceMap options.
Default: { js: "source-map", css: true }

Whether or not to generate source map. To disable source map, set the option to false.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    sourceMap: false
});

To customize the source map configuration, provide an object literal.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    sourceMap: {
        css: false
    }
});

# `react`

Type: false or (defaultOptions: PluginReactOptions) => PluginReactOptions
Default: defaultOptions => defaultOptions

Whether or not to transform React code. To disable React code transformation, set the option to false.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    react: false
});

To customize plugin-react, provide a function to extend the default options.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    react: defaultOptions => {
        return {
            ...defaultOptions,
            swcReactOptions: {
                ...(defaultOptions.swcReactOptions ?? {}),
                runtime: "classic"
            }
        };
    }
});

# `svgr`

Type: false or (defaultOptions: PluginSvgrOptions) => PluginSvgrOptions
Default: defaultOptions => defaultOptions

Whether or not to handle .svg files with plugin-svgr. When the option is set to false, the .svg files will be handled by the asset/resource rule.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    svgr: false
});

To customize plugin-svgr, provide a function extending the default options.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    svgr: defaultOptions => {
        return {
            svgrOptions: {
                ...(defaultOptions.svgrOptions ?? {}),
                ref: true
            }
            ...defaultOptions,

        }
    }
});

# Typings

When you reference an SVG asset in TypeScript code, TypeScript may prompt that the module is missing a type definition:

TS2307: Cannot find module './logo.svg' or its corresponding type declarations.

To fix this, you need to add type declaration for the SVG assets, create a src/env.d.ts file, and add the type declaration.

src/env.d.ts
declare module '*.svg' {
  export const ReactComponent: React.FunctionComponent<
    React.SVGProps<SVGSVGElement>
  >;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}

For additional information, refer to the plugin documentation.

# Import images

By default, plugin-svgr is configured to support named import for ReactComponent:

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

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

# `compressImage`

Type: false or (defaultOptions: PluginImageCompressOptions) => PluginImageCompressOptions
Default: defaultOptions => defaultOptions

Whether or not to compress images with plugin-image-compress. To disable image compression, set the option to false.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    compressImage: false
});

To customize plugin-image-compress, provide a function extending the default options.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    compressImage: defaultOptions => {
        return [
            ...defaultOptions,
            "pngLossless"
        ];
    }
});

# `verbose`

Type: boolean
Default: false

Start the Rsbuild process with verbose logging turned on.

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    verbose: true
});

# Configuration transformers

We do not guarantee that your configuration transformers won't break after an update. It's your responsibility to keep them up to date with new releases.

The predefined options are useful to quickly customize the default build configuration of @workleap/rsbuild-configs, but only covers a subset of an Rsbuild configuration. If you need full control over the configuration, you can provide configuration transformer functions through the transformers option of the defineBuildConfig function. Remember, no locked in ❤️✌️.

To view the default build configuration of @workleap/rsbuild-configs, have a look at the build.ts configuration file on GitHub.

# `transformers`

Type: ((config: RsbuildConfig, context: RsbuildConfigTransformerContext) => RsbuildConfig)[]
Default: []

transformer(config: RsbuildConfig, context: RsbuildConfigTransformerContext) => RsbuildConfig

rsbuild.build.ts
import { defineBuildConfig, type RsbuildConfig, type RsbuildConfigTransformer } from "@workleap/rsbuild-configs";

const forceNamedChunkIdsTransformer: RsbuildConfigTransformer = (config: RsbuildConfig) => {
    config.output = {
        ...(config.output ?? {}),
        filename: "[name].[contenthash].bundle.js"
    };

    return config;
};

export default defineBuildConfig({
    transformers: [forceNamedChunkIdsTransformer]
});

# Execution context

Generic transformers can use the context parameter to gather additional information about their execution context, like the environment they are operating in.

transformer.ts
export const transformer: RsbuildConfigTransformer = (config: RsbuildConfig) => {
    if (context.environment === "build") {
        config.output = {
            ...(config.output ?? {}),
            filename: "[name].[contenthash].bundle.js"
        };
    }

    return config;
}

environment: "dev" | "build" | "storybook"
verbose: boolean

# Add a CLI script

To create the bundle files for production, add the following script to your project package.json file:

package.json
{
    "build": "rsbuild build --config rsbuild.build.ts"
}

# Use environment variables

# cross-env

We recommend instead to define environment variables using cross-env. With cross-env, the environment variables will be made available to any Node.js files that are executed by the script process (build in the example below 👇):

package.json
{
    "build": "cross-env DEBUG=true rsbuild build --config rsbuild.build.ts"
}

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

if (process.env.DEBUG) {
    console.log("Configuring Rsbuild in debug mode!");
}

export default defineBuildConfig();

However, there's a catch. When using cross-env, the variables will not be available in the application files because cross-env only makes them available to files that are executed by the process at build time while the application files are executed at runtime by a browser.

To make them accessible to the application files, Rsbuild must be aware of those environment variables and render them into the compiled application files. This is the purpose of the environmentVariables option.

# `environmentVariables`

Type: Record<string, unknown>
Default: {}

First, define the variables with environmentVariables:

rsbuild.build.ts
import { defineBuildConfig } from "@workleap/rsbuild-configs";

export default defineBuildConfig({
    environmentVariables: {
        "DEBUG": process.env.DEBUG === "true"
    }
});

Then, use the variables in any application files:

src/App.tsx
export function App() {
    if (process.env.DEBUG) {
        console.log("The application has been bootstrapped in debug!");
    }

    return null;
}

The === "true" part of "DEBUG": process.env.DEBUG === "true" is very important, otherwise the environment variable value would be "true" instead of true.

By default, Rsbuild injects a few environment variables into the code using the source.define option. For additional information about these default environment variables, refer to the Rsbuild documentation.

# CSS modules typings

When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:

TS2307: Cannot find module './index.module.css' or its corresponding type declarations.

To fix this, you need to add a type declaration file for the CSS Modules, please create a src/env.d.ts file, and add the corresponding type declaration.

env.d.ts
/// <reference types="@rsbuild/core/types" />

Make sure the project have a dependency on @rsbuild/core.

# Monorepo

If your solution is a monorepo, ensure that projects referencing your packages that include CSS Modules, also include the necessary type definitions

For example, given the following structure:

workspace
├── app
├──── tsconfig.ts
├── packages
├──── components
├────── src
├───────── Button.tsx
├───────── Button.module.css
├───────── env.d.ts
├───────── tsconfig.ts
├── package.json

Copy the CSS Modules typings into the app web application own env.d.ts file, or include the components package's typings into the apps web application tsconfig.ts configuration file:

app/tsconfig.ts
{
    "extends": "@workleap/typescript-configs/web-application.json",
    "include": [
        ".",
        "../**/src/env.d.ts"
    ],
    "exclude": ["public", "dist", "node_modules"]
}

For additional information abour CSS modules type declaration, refer to the Rsbuild documentation.

# Try it 🚀

To test your new Rsbuild configuration, open a terminal at the root of the project and execute the CLI script added earlier. The build process should complete without outputting any error in the terminal and the bundle files should be available in the /dist folder (or any other distPath you configured).

# Configure for build

# Install the packages

# Configure Rsbuild

# HTML template

# Reference local assets

# Browserslist

# rsbuild.build.ts

# Use predefined options

# entry

# distPath

# assetPrefix

# plugins

# html

# minify

# optimize

# sourceMap

# react

# svgr