> For AI agents: the complete documentation index is available at https://rsbuild.rs/llms.txt, the full documentation bundle is available at https://rsbuild.rs/llms-full.txt.

# Dev server

Rsbuild provides two commands for serving your application locally:

- `rsbuild dev`: Compiles and serves the application with hot module replacement.
- `rsbuild preview`: Serves existing build output for local preview. It does not rebuild files or provide hot module replacement.

## Base path

By default, the Rsbuild server's base path is `/`. You can access output files like `index.html` and [public folder](https://rsbuild.rs/guide/basic/static-assets.md#public-folder) assets at `http://localhost:3000/`.

To change the server's base path, use [server.base](https://rsbuild.rs/config/server/base.md). For example, to access files at `http://localhost:3000/foo/`:

```ts title="rsbuild.config.ts"
export default {
  server: {
    base: '/foo',
  },
};
```

## View static assets

After starting the dev server, visit `/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:

![rsbuild-dev-server](https://assets.rspack.rs/rsbuild/assets/assets-report-page.png)
## 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](https://rsbuild.rs/config/server/base.md) and [source.entry](https://rsbuild.rs/config/source/entry.md) configurations.

When the entry is `index`, access the page at `/`. When the entry is `foo`, access the page at `/foo`.

When `server.base` is `/base`, access the index page at `/base`, and the foo page at `/base/foo`.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      index: './src/index.ts',
      foo: './src/pages/foo/index.ts',
    },
  },
};
```

### Fallback behavior

If a request meets the following conditions but no corresponding static asset exists, [server.htmlFallback](https://rsbuild.rs/config/server/html-fallback.md) triggers and falls back to `index.html` by default:

- The request method is `GET` or `HEAD`
- The `Accept` header contains `text/html` or `*/*`

### Custom fallback behavior

If Rsbuild's default [server.htmlFallback](https://rsbuild.rs/config/server/html-fallback.md) configuration doesn't meet your needs (for example, serving `main.html` when accessing `/`), use [server.historyApiFallback](https://rsbuild.rs/config/server/history-api-fallback.md) instead.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      main: './src/index.ts',
    },
  },
  server: {
    historyApiFallback: {
      index: '/main.html',
    },
  },
};
```

### HTML output path

Normally, `/` points to the dist root directory, and HTML files are output there. In this case, access HTML pages at `/some-path`.

If you output HTML files to other subdirectories using [output.distPath.html](https://rsbuild.rs/config/output/dist-path.md), access HTML pages at `/[htmlPath]/some-path` instead.

For example, if you set HTML files to output to the `html` directory, access index.html at `/html/`, and foo.html at `/html/foo`.

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

## Rspack dev server

Rsbuild includes its own lightweight dev server, which differs from the servers in Rspack CLI and webpack CLI and offers its own configuration options.

### Configuration

Rsbuild doesn't support Rspack's [devServer](https://rspack.rs/config/dev-server) config. Use Rsbuild's `dev` and `server` configs instead.

In Rsbuild, the `dev` config contains settings that only apply in development mode, while the `server` config applies to both dev and preview servers.

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

| Rspack CLI                                                                                        | Rsbuild                                                                               |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [devServer.client](https://rspack.rs/config/dev-server#devserverclient)                           | [dev.client](https://rsbuild.rs/config/dev/client.md)                                 |
| [devServer.compress](https://rspack.rs/config/dev-server#devservercompress)                       | [server.compress](https://rsbuild.rs/config/server/compress.md)                       |
| [devServer.devMiddleware.writeToDisk](https://rspack.rs/config/dev-server#devserverdevmiddleware) | [dev.writeToDisk](https://rsbuild.rs/config/dev/write-to-disk.md)                     |
| [devServer.headers](https://rspack.rs/config/dev-server#devserverheaders)                         | [server.headers](https://rsbuild.rs/config/server/headers.md)                         |
| [devServer.historyApiFallback](https://rspack.rs/config/dev-server#devserverhistoryapifallback)   | [server.historyApiFallback](https://rsbuild.rs/config/server/history-api-fallback.md) |
| [devServer.host](https://rspack.rs/config/dev-server#devserverhost)                               | [server.host](https://rsbuild.rs/config/server/host.md)                               |
| [devServer.hot](https://rspack.rs/config/dev-server#devserverhot)                                 | [dev.hmr](https://rsbuild.rs/config/dev/hmr.md)                                       |
| [devServer.liveReload](https://rspack.rs/config/dev-server#devserverlivereload)                   | [dev.liveReload](https://rsbuild.rs/config/dev/live-reload.md)                        |
| [devServer.open](https://rspack.rs/config/dev-server#devserveropen)                               | [server.open](https://rsbuild.rs/config/server/open.md)                               |
| [devServer.port](https://rspack.rs/config/dev-server#devserverport)                               | [server.port](https://rsbuild.rs/config/server/port.md)                               |
| [devServer.proxy](https://rspack.rs/config/dev-server#devserverproxy)                             | [server.proxy](https://rsbuild.rs/config/server/proxy.md)                             |
| [devServer.setupMiddlewares](https://rspack.rs/config/dev-server#devserversetupmiddlewares)       | [server.setup](https://rsbuild.rs/config/server/setup.md)                             |
| [devServer.static](https://rspack.rs/config/dev-server#devserverstatic)                           | [server.publicDir](https://rsbuild.rs/config/server/public-dir.md)                    |
| [devServer.watchFiles](https://rspack.rs/config/dev-server#devserverwatchfiles)                   | [dev.watchFiles](https://rsbuild.rs/config/dev/watch-files.md)                        |

> For more configurations, refer to [Config overview](https://rsbuild.rs/config/index.md).

## Middleware

Rsbuild's middleware implementation is built on [connect-next](https://github.com/rstackjs/connect-next), 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 [server.setup](https://rsbuild.rs/config/server/setup.md) configuration.

```ts title="rsbuild.config.ts"
export default {
  server: {
    setup: ({ server }) => {
      server.middlewares.use((req, res, next) => {
        next();
      });
    },
  },
};
```

2. In the Rsbuild plugin, you can register middleware through the [onBeforeStartDevServer](https://rsbuild.rs/plugins/dev/hooks.md#onbeforestartdevserver) hook.

```ts
const myPlugin = () => ({
  name: 'my-plugin',
  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](https://rsbuild.rs/api/javascript-api/instance.md#rsbuildcreatedevserver) method and use the `use` method to register middleware.

```ts
const server = await rsbuild.createDevServer();

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

### Integrate third-party server frameworks

When migrating from other server frameworks like Express, the original middleware may not work directly in Rsbuild. For example, Express-specific properties like `req.params`, `req.path`, `req.search`, and `req.query` aren't available in Rsbuild middleware.

To reuse existing middleware in Rsbuild, integrate your entire server application as middleware:

```ts title="rsbuild.config.ts"
import express from 'express';
import expressMiddleware from 'my-express-middleware';

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

app.use(expressMiddleware);

export default {
  server: {
    setup: ({ server }) => {
      server.middlewares.use(app);
    },
  },
};
```

## Custom server

To integrate Rsbuild's dev server into a custom server, use the `createDevServer` method to get the Rsbuild dev server instance and call its methods as needed.

For details, refer to [Rsbuild - createDevServer](https://rsbuild.rs/api/javascript-api/instance.md#rsbuildcreatedevserver).
