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

# router

- **类型：** `Object`
- **默认值：** `{}`

该配置项用于配置客户端路由，支持使用 Modern.js 默认提供的[约定式路由](/zh/guides/concept/entries.md#约定式路由)进行路由管理。

:::note
`router` 配置项**仅在使用约定式路由入口时生效**（即入口中存在 `routes/` 目录）。对于自控式路由入口或自定义入口，该配置不会生效。

在多入口应用中，可以通过 `defineRuntimeConfig` 的函数形式为不同入口配置不同的路由行为，详见[运行时配置介绍](/zh/configure/app/runtime/0-intro.md#多入口配置)。
:::

## basename

- **类型：** `string`
- **默认值：** `/`

设置客户端路由的 `basename`，通常用于应用需要部署在域名非根路径下的场景。

:::tip
推荐使用 [`server.baseUrl`](/zh/configure/app/server/base-url.md) 进行配置。
:::

## supportHtml5History

- **类型：** `boolean`
- **默认值：** `true`

值为 `true`，使用 `BrowserRouter`；否则使用 `HashRouter`。推荐使用 `BrowserRouter`。

:::warning
当开启 SSR 时，不支持设置 `supportHtml5History`。

:::

## useTransitions

- **类型：** `boolean`
- **默认值：** `undefined`，与 React Router 的默认行为一致，即开启

是否用 [`React.startTransition`](https://react.dev/reference/react/startTransition) 包裹路由状态更新。该值会透传给 React Router 的 [`<RouterProvider useTransitions>`](https://reactrouter.com/api/data-routers/RouterProvider)。

开启时，首屏 Data Loader 完成后的页面挂载和每次路由跳转都以并发方式渲染，好处是：

- 跳转时在新页面准备好之前保留旧页面，不会先显示加载状态。
- 渲染过程可以让出主线程，页面切换期间仍能响应用户输入。

同时会带来两个与同步渲染不同的行为：

- 渲染可能被丢弃后重新执行。组件函数体、`useMemo` 和 `useState` 的初始化函数、类组件构造函数可能执行多次，其中修改外部状态的代码（例如创建实例并赋值给全局变量、注册事件监听、上报埋点）也会重复执行。
- 渲染与提交之间可能有间隔。渲染时读取的外部状态，到 `useLayoutEffect` 中订阅时可能已经变化，间隔内发生的更新会丢失。

如果应用中存在上述写法且暂时无法改造，可以设置为 `false`，路由状态更新会改为同步渲染：

```ts title="src/modern.runtime.ts"
import { defineRuntimeConfig } from '@modern-js/runtime';

export default defineRuntimeConfig({
  router: {
    useTransitions: false,
  },
});
```

:::tip

- 该配置只影响路由状态更新。在业务代码中调用 `startTransition` 或 `useTransition` 触发的更新不受影响。
- 改造方式可参考 [React Router 文档](https://reactrouter.com/explanation/react-transitions)。
- `future.v7_startTransition` 已废弃。未设置 `useTransitions` 时，会使用 `future.v7_startTransition` 的值。

:::
