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

# router

- **Type:** `Object`
- **Default:** `{}`

This configuration item is used to configure client-side routing, supporting the use of [conventional routing](/guides/concept/entries.md#convention-routing) provided by Modern.js for routing management.

:::note
The `router` configuration item **only takes effect when using conventional routing entries** (i.e., when there is a `routes/` directory in the entry). For controlled routing entries or custom entries, this configuration will not take effect.

In multi-entry applications, you can configure different routing behaviors for different entries using the function form of `defineRuntimeConfig`. For more details, see [Runtime Configuration Introduction](/configure/app/runtime/0-intro.md#multi-entry-configuration).
:::

## basename

- **Type:** `string`
- **Default:** `/`

Sets the `basename` for client-side routing, typically used when the application needs to be deployed under a non-root path of the domain.

:::tip
It is recommended to use [`server.baseUrl`](/configure/app/server/base-url.md) for configuration.
:::

## supportHtml5History

- **Type:** `boolean`
- **Default:** `true`

If the value of `supportHtml5History` is `true`, `BrowserRouter` would be used, otherwise `HashRouter` would be used. `BrowserRouter` is recommended.

:::warning
When SSR is enabled, `supportHtml5History` is not supported.

:::

## useTransitions

- **Type:** `boolean`
- **Default:** `undefined`, which follows React Router's default behavior (enabled)

Whether to wrap router state updates in [`React.startTransition`](https://react.dev/reference/react/startTransition). The value is passed to React Router's [`<RouterProvider useTransitions>`](https://reactrouter.com/api/data-routers/RouterProvider).

When enabled, the page mount after the initial Data Loader finishes and every navigation are rendered concurrently. Benefits:

- During navigation, the current page stays on screen until the next page is ready, instead of showing a loading state first.
- Rendering can yield to the main thread, so the page keeps responding to user input while switching pages.

It also introduces two behaviors that differ from synchronous rendering:

- A render may be discarded and run again. Component bodies, `useMemo` and `useState` initializers, and class component constructors may run more than once, so code in them that changes external state (such as creating an instance and assigning it to a global variable, registering event listeners, or sending analytics) also runs more than once.
- There may be a gap between render and commit. External state read during render may have changed by the time it is subscribed to in `useLayoutEffect`, and updates that happen in the gap are lost.

If your application contains such code and cannot be refactored yet, set it to `false` to render router state updates synchronously:

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

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

:::tip

- This option only affects router state updates. Updates triggered by `startTransition` or `useTransition` in your own code are not affected.
- See the [React Router documentation](https://reactrouter.com/explanation/react-transitions) for how to make your code transition-safe.
- `future.v7_startTransition` is deprecated. When `useTransitions` is not set, the value of `future.v7_startTransition` is used.

:::
