[Mister-Hope]

Summary

vue-router 5.4 deprecates the router scrollBehavior option:

scrollBehavior is deprecated. Use ScrollRestoration and useScrollRestoration() from vue-router/experimental instead. See the migration guide.

@vuepress/client still sets it in createVueRouter(), so VuePress and downstream packages depend on a deprecated API (and packages using type-aware linting are warned about it). This PR migrates the core client to the replacement.

Closes #1726.

Changes

• Bump the vue-router catalog from ^5.2.0 to ^5.4.0.
• Install the ScrollRestoration plugin before the router in createVueApp().
• Register scroll restoration in the root component, and remove the scrollBehavior option from createVueRouter().

VuePress renders the page layout directly instead of wrapping it in a <RouterView>, so the restoration provided by onRouteRendered would be called in router.afterEach(), before the new page is rendered, and cross-page hash links would never scroll. useScrollRestoration() is therefore registered with manual: true, and the scroll is restored after mounting and after each route change, which keeps the previous behavior intact.

The plugin options require capture and restore to be passed explicitly (the documented app.use(ScrollRestoration, { router }) snippet does not type-check), so the defaults SCROLL_RESTORATION_CAPTURE_DEFAULT and SCROLL_RESTORATION_RESTORE_DEFAULT are used.

Tests

Added e2e/tests/router/scroll-restoration.spec.ts with a tall fixture page (e2e/docs/router/scroll-restoration.md), covering:

• navigating to another page resets the scroll to the top,
• navigating back restores the scroll position,
• a hash on another page, and an in-page hash, scroll to the anchor target,
• reloading restores the scroll position.

Verification

• pnpm lint and pnpm check-types pass.
• pnpm test:unit passes (666 tests).
• pnpm test:e2e passes: e2e:dev (87 tests) and e2e:build (94 tests).

Notes

router.options.scrollBehavior is no longer set, so packages that read or patch it must be migrated on top of this change:

• @vuepress/plugin-active-header-links sets it to undefined so that updating the hash programmatically does not trigger a scroll.
• @vuepress/theme-default wraps it to wait for its page transition before scrolling.

Both live in other repositories, so they will be handled in follow-up PRs. Note that #1724 patches scrollBehavior in the same place and will need to be rebased on top of this migration.

[coveralls]

Coverage Report for CI Build 38455032649

Coverage remained the same at 73.948%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	1087
Covered Lines:	800
Line Coverage:	73.6%
Relevant Branches:	552
Covered Branches:	412
Branch Coverage:	74.64%
Branches in Coverage %:	Yes
Coverage Strength:	48.34 hits per line

---

💛 - Coveralls