Rsbuild

Rsbuild is a high-performance build tool powered by Rspack.

Guide

• Introduction: Introduction to Rsbuild, including its core capabilities, performance model, ecosystem fit, and next steps.
• Quick start: Get started with Rsbuild by creating a project, starting the dev server, and building for production.
• Features: Overview of the main features supported by Rsbuild.
• Glossary: Glossary of Rsbuild and frontend build terms, including bundlers, CSR, environments, Module Federation, SSR, and SWC.
• AI: AI guide for Rsbuild covering Agent Skills, llms.txt, Markdown docs, and AGENTS.md context for coding assistants.
• React: This document explains how to use Rsbuild to build a React application.
• Vue: This document explains how to build Vue applications with Rsbuild, including Vue 2 support.
• Preact: Learn how to build a Preact application using Rsbuild.
• Svelte: Learn how to build a Svelte application using Rsbuild.
• Solid: Learn how to build a Solid application using Rsbuild.
• CLI: Rsbuild includes a lightweight CLI with commands like rsbuild dev and rsbuild build.
• Dev server: Rsbuild includes a built-in dev server that enhances the development experience.
• Output files: This section covers the output file directory structure and how to control output directories for different file types.
• Static assets: Rsbuild supports importing static assets, including images, fonts, audio, and video.
• HTML: During the build process, Rsbuild compiles HTML templates and template parameters to generate HTML files.
• JSON: Rsbuild supports importing JSON files in code, and also supports importing YAML and TOML files, converting them to JSON format.
• Wasm: Rsbuild provides native support for WebAssembly (WASM) modules, allowing you to import and use .wasm files directly in your project.
• TypeScript: Rsbuild supports TypeScript by default, allowing you to directly use .ts and .tsx files in your project.
• Web Workers: This page explains how to configure and use Web Workers in an Rsbuild project.
• Deployment: This section explains how to deploy Rsbuild projects to static hosting and runtime platforms.
• Configure Rspack: Rsbuild supports directly modifying the Rspack configuration object, and supports modifying the built-in Rspack configuration of Rsbuild through rspack-chain.
• Configure Rsbuild: Rsbuild provides a wide range of configuration options with sensible defaults for most use cases.
• Configure SWC: SWC (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on Rust.
• CSS: Rsbuild provides out-of-the-box support for CSS, including PostCSS, CSS Modules, CSS preprocessors, CSS inlining, and CSS compression.
• CSS Modules: CSS Modules allows you to write CSS in a modular way, and import these styles in JavaScript files.
• CSS-in-JS: This document outlines how to use common CSS-in-JS libraries in Rsbuild.
• Tailwind CSS v4: Use Tailwind CSS v4 in Rsbuild with the recommended @rsbuild/plugin-tailwindcss integration or the @tailwindcss/postcss plugin.
• Tailwind CSS v3: Tailwind CSS v3 guide covering key concepts, configuration, and practical usage in Rsbuild.
• UnoCSS: UnoCSS is the instant atomic CSS engine, which is designed to be flexible and extensible.
• Path aliases: Path aliases allow developers to define aliases for modules, making it easier to reference them in code.
• Environment variables: Rsbuild supports injecting environment variables or expressions into your code during the build.
• Hot module replacement: Hot module replacement guide covering key concepts, configuration, and practical usage in Rsbuild.
• Logging: Learn how logger, createLogger, customLogger, logLevel, and dev.client.logLevel relate to each other in Rsbuild.
• Browserslist: Rsbuild supports using Browserslist to specify which browsers should be supported in your web application.
• Browser compatibility: Browser compatibility guide covering key concepts, configuration, and practical usage in Rsbuild.
• Module Federation: Module Federation is an architectural pattern for decomposing JavaScript applications.
• Multi-environment builds: Rsbuild can build outputs for multiple environments in a single run. Use environments to build them in parallel and set a separate Rsbuild config for each one.
• Server-side rendering (SSR): This chapter introduces how to implement SSR functionality using Rsbuild.
• Testing: Rsbuild doesn't include built-in testing frameworks, but integrates seamlessly with popular testing tools.
• Code splitting: Code splitting is the process of breaking code into multiple chunks to enable on-demand loading and improve performance.
• Bundle size optimization: Bundle size optimization is critical for production builds because it directly affects user experience.
• Improve build performance: While Rsbuild optimizes build performance by default, performance issues can arise as your project grows.
• Inline static assets: Inlining static assets refers to embedding the content of a static asset directly in an HTML or JS file instead of linking to an external file.
• Upgrading Rsbuild: This section explains how to upgrade your project's Rsbuild dependencies to the latest version.
• Upgrading from v1 to v2: This document lists all breaking changes from Rsbuild v1 to 2.0. Use it as a migration reference.
• Upgrading from 0.x to v1: This document lists all breaking changes from Rsbuild 0.7 to 1.0. Use it as a migration reference.
• webpack: This section introduces how to migrate a webpack project to Rsbuild.
• Create React App: This chapter introduces how to migrate a Create React App (CRA) or CRACO project to Rsbuild.
• Vue CLI: This chapter introduces how to migrate a Vue CLI project to Rsbuild.
• Vite: This guide explains how to migrate a Vite project to Rsbuild.
• Vite plugin: This chapter introduces how to migrate a Vite plugin to Rsbuild plugin.
• Debug mode: Rsbuild provides a debug mode to troubleshoot problems. Add the DEBUG=rsbuild environment variable when you run a build to enable it.
• Build profiling: Running a performance analysis helps you identify bottlenecks in your project so you can optimize the right areas.
• Use Rsdoctor: Rsdoctor is a build analyzer tailored for the Rspack ecosystem.
• General FAQ: Frequently asked questions about Rsbuild, focused on core concepts, ecosystem positioning, and basic usage.
• Features FAQ: Frequently asked questions about Rsbuild, focused on feature support, tradeoffs, and ecosystem compatibility.
• Exceptions FAQ: Frequently asked questions about Rsbuild, focused on build-time and runtime troubleshooting.
• HMR FAQ: Frequently asked questions about Rsbuild, focused on HMR behavior and development-time updates.

Config

• Config overview: This page lists all the configurations for Rsbuild. See "Configure Rsbuild" for details.
• root: Specify the project root directory. Can be an absolute path, or a path relative to process.cwd().
• mode: Sets the Rsbuild build mode. Each mode applies different defaults and optimizations; for example, production minifies code by default.
• plugins: Reference for the Rsbuild plugins option, including behavior, defaults, configuration details, and usage examples.
• logLevel: This option also affects Rsbuild's log output in the browser. You can override this behavior through the client.logLevel option.
• splitChunks: splitChunks is used to configure Rsbuild's chunk splitting strategy.
• environments: Rsbuild supports building outputs for multiple environments. You can use environments to define different Rsbuild configurations for each environment.
• customLogger: Use customLogger to attach a logger instance to the current Rsbuild instance. Create it with createLogger() for isolated logging.
• dev.assetPrefix: Set the URL prefix of static assets in development mode.
• dev.browserLogs: Controls whether to forward browser runtime errors to the terminal.
• dev.cliShortcuts: Customize CLI shortcuts by providing a function that receives the default shortcuts array and returns a new one.
• dev.client: Configure the client code injected by Rsbuild during the development process. This can be used to set the WebSocket URL for HMR.
• dev.hmr: Refer to Hot Module Replacement for more information.
• dev.lazyCompilation: Enable lazy compilation (compilation on demand), implemented based on Rspack's lazy compilation feature.
• dev.liveReload: Whether to reload the page when source files are changed.
• dev.progressBar: Whether to render progress bars to display the build progress.
• dev.watchFiles: Watch specified files and directories for changes. When a change is detected, it can trigger a page reload or restart the dev server.
• dev.writeToDisk: Controls whether the build output from development mode is written to disk.
• resolve.aliasStrategy: Set the strategy for path alias resolution, to control the priority relationship between the paths option in tsconfig.
• resolve.alias: Create aliases for module paths to simplify import paths or redirect module references.
• resolve.conditionNames: Specifies the condition names used to match entry points in the exports field of a package.
• resolve.dedupe: Force Rsbuild to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.
• resolve.extensions: Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.
• resolve.mainFields: Controls the priority of fields in a package.json when locating a package's entry file.
• source.assetsInclude: Include additional files that should be treated as static assets.
• source.decorators: If you want to know the differences between different decorators versions, you can refer to: How does this proposal compare to other versions of decorators?
• source.define: Replaces variables in your code with other values or expressions at compile time. This enables different behavior between development and production builds.
• source.entry: source.entry is an object where the key is the entry name and the value is the path of the entry module or a description object.
• source.exclude: Exclude JavaScript or TypeScript files that do not need to be compiled by SWC.
• source.include: Specify additional JavaScript files that need to be compiled by SWC.
• source.preEntry: Add a script before the entry file of each page. This script will be executed before the page code.
• source.transformImport: Transform the import path to modularly import subpaths of third-party packages. The functionality is similar to babel-plugin-import.
• source.tsconfigPath: Configure a custom tsconfig.json file path to use, can be a relative or absolute path.
• output.assetPrefix: In production mode, use this option to configure the URL prefix for static assets, such as a CDN URL.
• output.autoExternal: Use output.autoExternal to automatically externalize dependencies declared in package.json.
• output.charset: The charset config sets the character encoding for output files, ensuring they display correctly across different environments.
• output.cleanDistPath: Configure whether to clean all files in the output directory before the build starts. The output directory is the output.distPath.root directory.
• output.copy: Copies the specified file or directory to the dist directory, implemented based on rspack.CopyRspackPlugin.
• output.cssModules: The CSS Modules feature in Rsbuild is based on the modules option of css-loader. You can refer to css-loader - modules to learn more.
• output.dataUriLimit: Set the size threshold to inline static assets such as images and fonts.
• output.distPath: Configure the directory for output files. Rsbuild outputs files to the specified subdirectory according to file type.
• output.emitAssets: Controls whether to emit static assets such as images, fonts, audio, video, etc.
• output.emitCss: Controls whether CSS is emitted to output bundles.
• output.externals: Use output.externals to specify which modules should not be bundled by Rsbuild, and instead use implementations provided by the external environment.
• output.filenameHash: Configure whether to add a hash value to output filenames.
• output.filename: After a production build, Rsbuild adds a hash to the filename by default. To disable this behavior, set output.filenameHash to false.
• output.injectStyles: Controls whether Rsbuild inlines CSS into JS files and injects it at runtime instead of extracting separate .css files.
• output.inlineScripts: Whether to inline output scripts files (.js files) into HTML with script tags.
• output.inlineStyles: Whether to inline output style files (.css files) into HTML with style tags.
• output.legalComments: Controls how legal comments are handled in the build output.
• output.manifest: The manifest file contains information about all assets and the mapping between entry modules and assets.
• output.minify: Controls whether code minification is enabled, and provides configuration options for the minimizers.
• output.module: Whether to output JavaScript files in ES modules format.
• output.overrideBrowserslist: Specifies the range of target browsers that the project is compatible with.
• output.polyfill: When you enable polyfill injection, make sure core-js v3 is installed in your project, which is a popular polyfill library for JavaScript.
• output.sourceMap: Configures whether to generate source map files and which source map format to generate.
• output.target: Rsbuild supports multiple build targets for running in different environments.
• html.appIcon: Reference for the Rsbuild html.app-icon option, including behavior, defaults, configuration details, and usage examples.
• html.crossorigin: Set the crossorigin attribute of the script and style tags.
• html.favicon: Reference for the Rsbuild html.favicon option, including behavior, defaults, configuration details, and usage examples.
• html.inject: Reference for the Rsbuild html.inject option, including behavior, defaults, configuration details, and usage examples.
• html.meta: If the HTML template used in the current project already contains the charset or viewport meta tags, then the tags in the HTML template take precedence.
• html.mountId: By default, the root element is included in the HTML template for component mounting. The element id can be modified through mountId.
• html.outputStructure: Define the directory structure of the HTML output files.
• html.scriptLoading: Specifies how script tags generated by Rsbuild are loaded.
• html.tags: Modifies the tags that are injected into the HTML page.
• html.templateParameters: Define the parameters in the HTML template, see HTML Template - Template Parameters for detailed usage.
• html.template: Specifies the file path for the HTML template, which can be a relative or absolute path.
• html.title: If the HTML template used in the current project already includes the title tag, the html.title will not take effect.
• server.base: server.base is used to configure the base path of the server.
• server.compress: Configure whether to enable gzip compression for static assets served by the dev server or preview server.
• server.cors: Configure CORS options for the dev server or preview server, based on the cors middleware.
• server.headers: Adds headers to all responses sent from Rsbuild server. This configuration directly leverages Node.js response.setHeader() method under the hood.
• server.historyApiFallback: historyApiFallback is used to support routing based on the history API.
• server.host: Specify the host that the Rsbuild server listens to.
• server.htmlFallback: Reference for the Rsbuild server.html-fallback option, including behavior, defaults, configuration details, and usage examples.
• server.https: Configure HTTPS options to enable HTTPS server. When enabled, HTTP server will be disabled.
• server.middlewareMode: Whether to create Rsbuild's server in middleware mode, which is useful for integrating with other servers.
• server.open: server.open configures which page URLs Rsbuild should automatically open in the browser after starting the server.
• server.port: By default, the Rsbuild server listens on port 3000 and automatically increments the port when it's occupied.
• server.printUrls: Controls whether and how server URLs are printed when the server starts.
• server.proxy: Configure proxy rules for the dev server or preview server, and forward requests to the specified service.
• server.publicDir: By default, Rsbuild uses the public directory for serving public assets. Files in this directory are served at server.base path (default /).
• server.setup: Run setup logic when the Rsbuild dev server or preview server starts, such as registering custom middleware or running pre-start tasks.
• server.strictPort: Controls whether Rsbuild throws an error instead of using the next available port when the specified port is occupied.
• security.nonce: Adds a nonce attribute to script resources injected into HTML. This lets the browser decide whether inline scripts with matching nonce values can be executed.
• security.sri: Adds an integrity attribute to script and link tags injected into HTML so the browser can verify the resource's integrity and prevent tampering.
• tools.bundlerChain: Reference for the Rsbuild tools.bundler-chain option, including behavior, defaults, configuration details, and usage examples.
• tools.cssExtract: Rsbuild uses the CssExtractRspackPlugin plugin by default to extract CSS into separate files.
• tools.cssLoader: Rsbuild uses css-loader by default to handle CSS resources. You can modify the options of css-loader through tools.cssLoader.
• tools.htmlPlugin: The configs of html-rspack-plugin can be modified through tools.htmlPlugin.
• tools.lightningcssLoader: You can set the options for builtin:lightningcss-loader through tools.lightningcssLoader.
• tools.postcss: Rsbuild integrates PostCSS by default. You can configure postcss-loader through tools.postcss.
• tools.rspack: The built-in Rspack config in Rsbuild may change with iterations, and these changes will not be reflected in semver.
• tools.styleLoader: The config of style-loader can be set through tools.styleLoader.
• tools.swc: You can set the options of builtin:swc-loader through tools.swc.
• performance.buildCache: When enabled, Rspack will store the build snapshots in the cache directory.
• performance.dnsPrefetch: Reference for the Rsbuild performance.dns-prefetch option, including behavior, defaults, configuration details, and usage examples.
• performance.preconnect: Reference for the Rsbuild performance.preconnect option, including behavior, defaults, configuration details, and usage examples.
• performance.prefetch: Inject the link tags for the static assets generated by Rsbuild.
• performance.preload: Inject the link tags for the static assets generated by Rsbuild.
• performance.printFileSize: Whether to print the file sizes after production build.
• performance.removeConsole: Whether to remove console.[methodName] in production build.
• moduleFederation.options: Used to configure the Rspack's Module Federation plugin (Module Federation v1.5).

Plugin

• Plugin list: You can read about the functionality of Rsbuild plugins and how to develop an Rsbuild plugin in the Plugin System documentation.
• React plugin: The React plugin provides support for React, integrating features such as JSX compilation and React Refresh.
• SVGR plugin: By default, Rsbuild treats SVG files as static assets. For processing rules, see Static assets.
• Vue plugin: The Vue plugin provides support for Vue 3 SFC (Single File Components). The plugin internally integrates rspack-vue-loader.
• Preact plugin: The Preact plugin provides support for Preact, integrating features such as JSX compilation and React aliasing.
• Svelte plugin: The Svelte plugin provides support for Svelte components (.svelte files). The plugin internally integrates svelte-loader.
• Solid plugin: The Solid plugin provides support for Solid features. The plugin internally integrates babel-preset-solid.
• Babel plugin: Babel plugin documentation covering plugin capabilities, setup, and available options.
• Tailwind CSS plugin: Integrate Tailwind CSS v4 in Rsbuild with a plugin based on @tailwindcss/webpack, avoiding @tailwindcss/postcss transforms for better build performance.
• Sass plugin: Use Sass as the CSS preprocessor, implemented based on sass-loader.
• Less plugin: Use Less as the CSS preprocessor, implemented based on less-loader.
• Plugin development: Rsbuild's architecture is centered on a plugin system.
• Plugin API: This page explains the type definitions and usage of Rsbuild plugin APIs.
• Plugin hooks: This page outlines the plugin hooks available for Rsbuild plugins.

API

• JavaScript API: Overview of the Rsbuild JavaScript API, including core methods, instance APIs, environment APIs, and server APIs.
• Rsbuild core: Reference for the Rsbuild JavaScript API, covering createRsbuild, loadConfig, loadEnv and related methods.
• Rsbuild instance: Reference for the Rsbuild JavaScript API, covering rsbuild.context, rsbuild.build, rsbuild.startDevServer and related methods.
• Rsbuild types: Reference for the Rsbuild JavaScript API, covering RsbuildInstance, RsbuildConfig, NormalizedConfig and related methods.
• Server API: Reference for the Rsbuild JavaScript API, covering How to use, Example, Shared API and related methods.
• Environment API: Reference for the Rsbuild JavaScript API, covering Environment context, Environment API and related methods.

Blog

• Rsbuild blogs: This page collects blog posts about Rsbuild.
• Announcing Rsbuild 2.0: Rsbuild 2.0 is out, featuring Rspack 2.0, RSC support, and more modern defaults.
• Announcing Rsbuild 1.0: Rsbuild 1.0 officially launches with faster builds, simpler configuration, a growing plugin ecosystem, and broader adoption across Rstack.
• Announcing Rsbuild 0.7: Rsbuild 0.7 adds Storybook support, faster Sass compilation, and typed CSS Modules.
• Announcing Rsbuild 0.6: Rsbuild 0.6 enables the error overlay by default, adds Vue JSX HMR, and introduces a new transform API.
• Announcing Rsbuild 0.5: Rsbuild 0.5 adds Lightning CSS, custom server support, and more flexible minify options.
• Announcing Rsbuild 0.4: Rsbuild 0.4 adds built-in Module Federation config and updates plugin hook ordering and default behavior.
• Announcing Rsbuild 0.3: Rsbuild 0.3 adds Module Federation support and updates TOML/YAML plugins, the JavaScript API, and Node target behavior.
• Announcing Rsbuild 0.2: Rsbuild 0.2 updates core configuration such as targets and entry, and redesigns the Babel plugin API.
• Announcing Rsbuild 0.1: Rsbuild 0.1 introduces an Rspack-based build tool with faster builds, simpler configuration, and multi-framework support.