docs: document useRouter push/replace void return and useTransition migration (#100420)
### What?
Documents that `router.push()` and `router.replace()` in the App Router
(`next/navigation`) return `void` instead of a `Promise`, and provides
migration guidance and code examples showing how to use React's
`useTransition` to track pending navigation state.
### Why?
In the Pages Router (`next/router`), `router.push()` and
`router.replace()` returned a `Promise<boolean>` that developers could
`await` to execute code after a route change. In the App Router,
navigations are non-blocking transitions integrated with React's
transition system and return `void`. This breaking difference was not
documented in the `useRouter` API reference or the App Router migration
guide, leading to confusion when migrating existing codebases.
### How?
- Updated `docs/01-app/03-api-reference/04-functions/use-router.mdx`:
- Added callout notes to `router.push()` and `router.replace()`
explaining the `void` return type and referencing `useTransition`.
- Added a migration bullet point under "Migrating from `next/router`".
- Added an example demonstrating how to track pending navigation state
with React's `useTransition` (`startTransition` / `isPending`).
- Updated `docs/01-app/02-guides/migrating/app-router-migration.mdx`:
- Added migration notes and dual-language (TSX/JSX) switcher examples
under Step 5 ("Migrating Routing Hooks") explaining how to migrate from
`await router.push(...)` using `useTransition`.
Closes #61737
Showing
Please
register
or
sign in
to comment