* fix(router): honor hybrid pages route priority
* fix(router): share hybrid owner decision with client navigation
PR #1997 fixed the server-side route ownership for direct document loads,
but the same invariant broke for client-side soft navigations and the
matching prefetch path:
- navigateClientSide() always delegated to the App runtime's RSC fetch,
even when the Pages route had higher priority. renderPagesFallback()
short-circuits RSC requests with null, so the App catch-all won.
- prefetchUrl() prefetched an RSC stream for any URL that matched an App
route, again ignoring Pages ownership.
- The Pages entry was loaded on every hybrid request, even when a static
App route had already matched (Pages can never win in that case).
Expose the Pages route manifest on the client via a new
__VINEXT_PAGES_LINK_PREFETCH_ROUTES__ window global emitted by both the
App and Pages browser entries. The link shim consults a shared
resolveHybridClientRouteOwner helper that mirrors the server-side
pagesRouteHasPriorityOverAppRoute comparison. When Pages owns the URL,
the click handler issues a window.location navigation and the prefetch
path returns early.
Gate the renderPagesFallback call behind a static-App-route check in
handleAppRscRequest: when a static App route matches, the bridge
cannot win, so skip the eager Pages entry load. Centralise the
comparison in a new resolveHybridRouteOwner helper so server and
client reach the same answer for the same (URL, route pair).
Adds the missing client-navigation coverage to the use-params e2e
fixture (Link from /app/ to /pages-dir/foobar) and unit tests for
the shared owner decision.
* fix(router): mirror server hybrid owner decision on the client
PR review flagged two split-brain bugs in the previous hybrid
ownership fix: a hand-copied client comparator and a Link-only
ownership gate that left programmatic App Router navigations on
the wrong path.
The hand-copied routePrecedence in hybrid-client-route-owner.ts
omitted the static-prefix reduction that lives in
routing/utils.ts#routePrecedence, and used a strict-less-than
comparison that returned App for identical dynamic patterns. The
server returns Pages for both cases (Pages providers sort ahead
of App providers, and routePrecedence subtracts 50 per static
prefix segment). The split produced a real ownership disagreement
on overlapping patterns like /_sites/:slug* (Pages) vs /:slug*
(App).
Add a shared compareHybridRoutePatterns to routing/utils.ts as
the single source of truth: the static/dynamic short-circuits plus
a sortRoutes call (which carries the static-prefix reduction and
the Pages-first equal-pattern tiebreak). The server
pagesRouteHasPriorityOverAppRoute and the client
resolveHybridClientRouteOwner both delegate to it, so they
cannot diverge. Drop the hand-copied routePrecedence entirely.
Wire the ownership check at the App navigation runtime boundary
so useRouter().push, useRouter().replace, gesturePush, and form
submits all get the same hard-nav contract as the Link click
handler. Specifically:
- navigateClientSide: after same-origin normalization, if Pages
owns the URL, hard-navigate via window.location and return
(matching the existing external-URL branch).
- _appRouter.prefetch: short-circuit RSC URL construction for
Pages-owned targets so we do not warm an unusable cache entry.
Centralise the existing two inline hard-nav branches in
navigateClientSide into a hardNavigateTo helper for clarity.
Tests:
- Direct unit tests for compareHybridRoutePatterns covering
identical-dynamic tiebreak, static-prefix dynamic overlap,
static-prefix catch-all overlap, and infix-static bonus.
- Direct unit tests for resolveHybridClientRouteOwner mirroring
the server assertions plus a basePath-stripping test.
- e2e: useRouter().push('/pages-dir/foobar') from an App page
resolves to the Pages document.
- e2e: useRouter().prefetch('/pages-dir/foobar') issues zero
RSC requests for the target URL.
* docs(router): fix stale score in static-prefix catch-all test comment
The hand-copied comparator note quoted the dynamic-segment scores
(51 / 1000) for the optional-catch-all example (/_sites/:slug*
vs /:slug*). The current optional-catch-all scoring actually
produces 1951 vs 2000. The test assertion was correct; only the
comment was stale.
* test(use-params): fix direct-load single dynamic param to use /a instead of /a/b
* fix(router): compare hybrid routes structurally
* fix(router): reject hybrid route conflicts
* fix(router): refresh hybrid route ownership
* fix(router): preserve hybrid routing lifecycle
* fix(router): recheck pages routes after rewrites
* fix(router): preserve rewritten pages queries
* fix(router): preserve rewritten route ownership
* fix(router): resolve client rewrites sequentially
* fix(router): apply rewrite phases sequentially
* fix(router): preserve rewrite params and endpoints
* fix(router): hand off endpoint navigations
* fix(router): preserve rewrite fragment params
* test(e2e): avoid hybrid fixture route conflicts
* test(pages): await async config validation
* test(hybrid): avoid duplicate page fixtures
* chore(router): clarify hybrid priority semantics
* refactor(router): remove duplicate app route matcher
* docs(router): clarify client hybrid comparator
---------
Co-authored-by: James <james@eli.cx>
* fix(pages-router): hard-navigate to App Router destinations from Pages Router links
When a Pages Router <Link> targets an App Router route (detected via the
prefetch manifest and recorded as `components[path] = { __appRouter: true }`),
`performNavigation` now checks for that marker and immediately calls
`window.location.assign/replace` instead of attempting a Pages Router SPA
fetch cycle that cannot succeed.
Mirrors Next.js router.ts:1448-1453. Fixes the deploy-suite test
`pages-to-app-routing > should work using browser`.
- packages/vinext/src/shims/router.ts: add __appRouter hard-nav guard
- tests/fixtures/app-basic/app/about/page.tsx: add id="app-page" to <h1>
- tests/fixtures/app-basic/pages/pages-to-app/[slug].tsx: new GSSP fixture page
- tests/e2e/app-router/pages-to-app-routing.spec.ts: new Playwright regression test
* fix(pages-router): replace no-explicit-any cast with in-operator type narrowing
`(getPagesRouterComponentsMap()[_appPath] as any)?.__appRouter` triggered
the `no-explicit-any` lint rule. Replace with a two-step lookup that uses
the `in` operator so TypeScript narrows the union type
`{ __appRouter: true } | Record<string, unknown>` without an `any` cast.
* fix(pages-router): normalize trailing slash in __appRouter marker key, rename locals, pin fast-path test
- Strip trailing slash on both the write side (markAppRouteDetectedOnPrefetch)
and the read side (performNavigation) so the marker key agrees when
trailingSlash:true adds a slash to the prefetch URL but not to the nav URL
(or vice-versa via router.prefetch with a raw un-normalised path).
Mirrors Next.js: removeTrailingSlash(removeBasePath(pathname)) at router.ts:1442.
- Rename _appPath/_appPathEntry to appPath/appPathNorm/appPathEntry (they are
used, not ignored; the underscore prefix was misleading).
- Add two new unit assertions in pages-router-app-prefetch-detection.test.ts:
one pins that the marker key is always stored without trailing slash, and one
pins that performNavigation calls window.location.assign (the fast-path) when
the __appRouter marker is present, so a regression in the new code path cannot
be silently masked by the pre-existing fallback.
* test(pages-router): address review nits in pages-to-app navigation tests
- e2e: wait for App Router hydration after the hard navigation so the
test asserts the App Router landing explicitly instead of only
matching the new DOM
- unit: drop the unnecessary microtask tick before asserting
window.location.assign — the fast path has no await before it, so
asserting synchronously also pins that the hard navigation cannot
lose a race against the SPA path
* fix(pages-router): mark app routes as detected on prefetch (#1526)
In a hybrid Pages + App Router app, when the Pages Router prefetches a
`<Link href>` whose target is actually an App Router route, Next.js marks
the route on the Pages Router singleton with
`router.components[urlPathname] = { __appRouter: true }` (driven by the
`_bfl` bloom filter at packages/next/src/shared/lib/router/router.ts:2525).
The Next.js deploy test `test/e2e/app-dir/app/index.test.ts` ("should
successfully detect app route during prefetch") asserts this via
`window.next.router.components["/dashboard"]`.
Vinext previously did not expose `components` and did not record App Router
prefetch targets, so the assertion never resolved.
This commit:
- adds a shared `components` map (via `Symbol.for` for module-split safety)
on the Pages Router singleton, mirrored onto `window.next.router`,
- threads the App Router prefetch manifest into the Pages Router client
entry so the same matcher Link uses for App Router auto-prefetch can run
in Pages-only-entry pages,
- marks the target on `components` with `{ __appRouter: true }` from both
`Router.prefetch` and `<Link>` Pages-mode prefetch when the target
matches the App Router manifest.
* fix(app-route-detection): drop unused exports flagged by knip
Both `matchesAppRoute` and `PagesRouterComponentsMap` are only used
inside this module — knip rightly flagged them as unused exports.
Internalize both.
James Anderson