#Dev server

Rsbuild includes a built-in dev server designed to improve the development experience. When you run rsbuild dev or rsbuild preview, the server starts and provides features like page preview, routing, and hot module replacement.

#Base path

By default, the Rsbuild server's base path is /. Access output files like index.html and public folder assets at http://localhost:3000/.

Modify the server's base path using server.base. To access files at http://localhost:3000/foo/, configure:

export default {
  server: {
    base: '/foo',
  },
};

#View static assets

After starting the dev server, access /rsbuild-dev-server to view all static assets generated during the current build.

For example, open http://localhost:3000/rsbuild-dev-server in your browser:

#Page routing

The Rsbuild server provides default routing conventions and allows customization through configuration.

#Default behavior

The Rsbuild server generates page routes based on the server.base and source.entry configurations.

When entry is index, the page can be accessed via /; when entry is foo, the page can be accessed via /foo.

When server.base is /base, the index page can be accessed via /base and the foo page can be accessed via /base/foo.

export default {
  source: {
    entry: {
      index: './src/index.ts',
      foo: './src/pages/foo/index.ts',
    },
  },
};

#Fallback behavior

By default, requests that meet the following conditions fall back to index.html when the corresponding resource is not found:

• The request is a GET or HEAD request
• The request accepts text/html (the request header accept type is text/html or */*)

export default {
  server: {
    htmlFallback: 'index',
  },
};

#Custom fallback behavior

If Rsbuild's default server.htmlFallback configuration does not meet your needs, for example, if you want to access main.html when accessing /, you can configure it using server.historyApiFallback.

export default {
  source: {
    entry: {
      main: './src/index.ts',
    },
  },
  server: {
    htmlFallback: false,
    historyApiFallback: {
      index: '/main.html',
    },
  },
};

#HTML output path

Normally, / points to the dist root directory, and HTML files are output to the dist root directory. In this case, you can access the corresponding HTML page at /some-path.

If you output HTML files to other subdirectories by modifying output.distPath.html, you need to access the corresponding HTML page at /[htmlPath]/some-path.

For example, if you set HTML files to be output to the HTML directory, index.html will be accessed at /html/, and foo.html will be accessed at /html/foo.

export default {
  source: {
    entry: {
      index: './src/index.ts',
      foo: './src/pages/foo/index.ts',
    },
  },
  output: {
    distPath: {
      html: 'html',
    },
  },
};

#Rspack dev server

Rsbuild has a built-in lightweight dev server that differs from the dev servers built into Rspack CLI or webpack CLI. There are some differences between them, including different configuration options.

#Comparison

Compared to the dev server built into Rspack CLI, Rsbuild's dev server has the following differences:

• Configuration: Rsbuild provides richer server configuration options.
• Log Format: The log format of Rspack CLI is basically consistent with webpack CLI, while Rsbuild's logs are clearer and more readable.
• Dependencies: Rsbuild is built on lightweight libraries like connect, which has fewer dependencies and faster startup speed compared to express used by @rspack/dev-server.

#Configuration

Rsbuild does not support using Rspack's devServer config. Instead, you can use Rsbuild's dev and server configs.

In Rsbuild, dev contains configurations that only work in development mode, while the server config works for both dev and preview servers.

Below are the Rsbuild configuration options that correspond to the Rspack CLI's devServer config:

For more configurations, please refer to Config Overview.

#Middleware

Rsbuild's middleware implementation is built on connect, a lightweight HTTP server framework, and uses the standard Node.js request and response objects for handling HTTP interactions.

#Register middleware

Rsbuild provides three ways to register middleware:

1. Use the dev.setupMiddlewares configuration.

export default {
  dev: {
    setupMiddlewares: (middlewares) => {
      middlewares.push((req, res, next) => {
        next();
      });
    },
  },
};

2. In the Rsbuild plugin, you can register middleware through the onBeforeStartDevServer hook.

const myPlugin = () => ({
  setup(api) {
    api.onBeforeStartDevServer(({ server }) => {
      server.middlewares.use((req, res, next) => {
        next();
      });
    });
  },
});

3. When using the Rsbuild JavaScript API, you can create a dev server instance through the rsbuild.createDevServer method and use the use method to register middleware.

const server = await rsbuild.createDevServer();

server.middlewares.use((req, res, next) => {
  next();
});

#Integrate third-party server frameworks

When migrating from other server frameworks (such as Express), the original middleware may not 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 reuse existing middleware in Rsbuild, you can use the following method to introduce the server application as a whole as middleware:

import express from 'express';
import expressMiddleware from 'my-express-middleware';

// Initialize Express app
const app = express();

app.use(expressMiddleware);

export default {
  dev: {
    setupMiddlewares: (middlewares) => {
      middlewares.unshift(app);
    },
  },
};

#Custom server

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.