Limits of Framework7 Router Navigation Guards for Aborting Page Transitions During Failed Upgrades

Short answer

Navigation guards in Framework7 can abort a transition, but aborting only guarantees that the router returns to the previous view — it does not guarantee restoration of that view's transient state, and it does not roll back side effects (theme changes, injected scripts, partially applied upgrade logic) that already ran. Whether the previous view survives intact depends on route caching, and the guard API you must use differs between v5 and v6.

Confirmed behavior vs. likely explanation

Confirmed, well-established behavior:

• In v5, a guard (e.g. beforeRoute-style hooks) returning false (or a Promise resolving to false) cancels the navigation and the router stays on the current view.
• In v6, the guard surface was reworked around beforeRouteEnter / beforeRouteLeave returning Promises that resolve to false (cancel) or a redirect target. A guard written for v5 will not necessarily behave identically after upgrading to v6 — check which hook signature your code actually uses.
• If the route has cache: true, the previous page's component instance is retained, so aborting keeps its DOM and component state. If caching is disabled, the view is destroyed and re-created on the next navigation, losing unsaved form data and AJAX-loaded content.

Likely explanation (mark for review against your exact version): the router restores the view, not the application state. Anything the failed upgrade already mutated — theme classes applied in onPageInit, injected scripts, global stores — is outside the router's rollback scope.

Limits and side effects

• No transactional rollback. Aborting is a routing decision, not an undo mechanism. Theme changes applied before the guard runs will persist, potentially leaving a mismatched style on the restored page.
• Cache residue. With caching enabled, DOM mutations made during the aborted transition can linger in the cached page until it is re-rendered.
• Stack mismatch. With nested routes, tabs, or modals, an aborted transition can leave the URL and the visible view out of sync; verify view.router.currentRoute after the abort.

Practical recommendation

1. Confirm your version and hook style: check framework7 in package.json, then verify whether your guards use the v5 boolean style or v6 beforeRouteEnter/beforeRouteLeave.
2. Treat the guard as a gate, not a recovery mechanism: run upgrade validation before allowing navigation, and defer theme/asset injection until after the guard passes.
3. Enable route caching for views whose state must survive an aborted upgrade, and persist critical form state outside the component (store or sessionStorage).
4. Test explicitly: simulate a failing upgrade, return false from the guard, and diff the DOM and theme classes before/after to confirm what actually survived.

One missing detail that changes the recommendation: your Framework7 version. If you are on v5 with a planned v6 upgrade, audit every guard now — the hook refactor is the most likely silent breakage point.