Rsbuild comes with a built-in dev server designed to improve the development experience. When you run the rsbuild dev
or rsbuild preview
commands, the server will start, providing features such as page preview, routing, and hot module reloading.
By default, the base path of the server is /
, and users can access output files such as index.html
and public folder assets through http://localhost:3000/.
Rsbuild supports modifying the base path of the server through server.base. If you to access these files through http://localhost:3000/foo/
, you can configure the following:
Rsbuild Server offers a set of default routing convention, and allows users to customize it through configurations.
Rsbuild Server will generate the corresponding page route based on the server.base and source.entry configurations.
When entry is index, the page can be accessed through /
; when entry is foo, the page can be accessed through /foo
.
When server.base is /base
, the index page can be accessed through /base
and the foo page can be accessed through /base/foo
.
By default, when the request meets the following conditions and the corresponding resource is not found, it will fallback to index.html
:
GET
or HEAD
requesttext/html
(the request header accept type is text/html
or */*
)When Rsbuild's default server.htmlFallback configuration cannot meet your needs, for example, if you want to be able to access main.html
when accessing /
, you can set it up using server.historyApiFallback.
Normally, /
points to the dist root directory, and the HTML file is output to the dist root directory. At this time, the corresponding HTML page can be accessed through /some-path
.
If you output HTML files to other subdirectories by modifying output.distPath.html, you need to access the corresponding HTML page through /[htmlPath]/some-path
.
For example, if you set the HTML file to be output to the HTML
directory, index.html will be accessed through /html/
, and foo.html will be accessed through /html/foo
.
The built-in dev server of Rspack CLI is @rspack/dev-server. Rsbuild does not use @rspack/dev-server
, but instead implemented its own more lightweight version.
The dev server of Rsbuild and @rspack/dev-server
have the following differences:
@rspack/dev-server
is based on express with many third-party dependencies. Rsbuild, on the other hand, uses lighter libraries such as connect
.Rsbuild does not support using Rspack's devServer config. Instead, you can use Rsbuild's dev
and server
configs.
In Rsbuild, dev
contains some configs that are only work in development mode, while the server
config works for both dev and preview servers.
Below are the Rsbuild configs that correspond to the Rspack CLI's devServer
config:
For more configurations, please refer to Config Overview.
Rsbuild server does not use any Node.js frameworks, and the req
and res
provided by Rsbuild middleware are both native Node.js objects.
This means that when you migrate from other server-side frameworks (such as Express), the original middleware may not necessarily be used directly in Rsbuild. For example, the req.params
,req.path
, req.search
, req.query
and other properties provided by Express cannot be accessed in the Rsbuild middleware.
If you need to use existing middleware in Rsbuild, this can be done by passing the server application as middleware as follows:
If you want to integrate Rsbuild dev server into a custom server, you can get the instance methods of Rsbuild dev server through the createDevServer
method of Rsbuild and call them on demand.
For details, please refer to Rsbuild - createDevServer.