App Router client navigation double-flashes Suspense fallbacks and janky back-button scroll restoration

[NathanDrake2406]

Summary

Client-side navigation in vinext App Router visibly commits partial destination UI (Suspense fallbacks) instead of keeping the old content on screen until the new content is ready. This produces a double-flash on list/detail transitions and janky scroll restoration on back/forward navigation.

This does not happen in the equivalent app running on Next.js.

Reproduction

Any vinext App Router app with async server components inside Suspense boundaries will show this. Minimal pattern:

Page (server component):

// app/page.tsx
import { Suspense } from "react";
import { FilterToggle } from "./FilterToggle";

async function ItemList({ filter }: { filter: string }) {
  // Simulate DB query — any async server component triggers it
  await new Promise((r) => setTimeout(r, 300));
  const items = filter
    ? [{ id: 1, name: `Filtered: ${filter}` }]
    : [{ id: 1, name: "Item A" }, { id: 2, name: "Item B" }, { id: 3, name: "Item C" }];
  return <ul>{items.map((i) => <li key={i.id}>{i.name}</li>)}</ul>;
}

export default async function Page({ searchParams }: { searchParams: Promise<{ filter?: string }> }) {
  const { filter = "" } = await searchParams;
  return (
    <div>
      <h1>{filter ? `Filtered: ${filter}` : "All items"}</h1>
      <FilterToggle current={filter} />
      <Suspense fallback={<div style={{ height: 400 }} />}>
        <ItemList filter={filter} />
      </Suspense>
    </div>
  );
}

Client component:

// app/FilterToggle.tsx
"use client";
import { useRouter } from "next/navigation";

export function FilterToggle({ current }: { current: string }) {
  const router = useRouter();
  return (
    <button onClick={() => router.push(current ? "/" : "/?filter=active")}>
      {current ? "Clear filter" : "Apply filter"}
    </button>
  );
}

Steps — double flash

1. vinext dev, open the page
2. Click "Apply filter" — navigates to /?filter=active
3. Click "Clear filter" — navigates back to /
4. Observe: the heading updates to "All items" while the Suspense fallback (empty space) is visible, then the list pops in afterward — two visible stages instead of one clean swap

Steps — back button scroll jank

1. Add a detail route (app/item/[id]/page.tsx) with an async server component
2. Scroll down on the list page
3. Click a link to /item/1
4. Press browser back
5. Observe: scroll position jumps before the list content is ready, producing a visual stutter

What I found

The RSC navigation render in packages/vinext/src/server/app-browser-entry.ts uses flushSync:

const rscPayload = await createFromFetch(Promise.resolve(navResponse));
flushSync(() => {
  getReactRoot().render(rscPayload as ReactNode);
});

flushSync forces React to synchronously commit the new tree, including Suspense fallbacks for any unresolved async server components. Next.js uses startTransition here instead, which tells React to keep the old UI visible until all Suspense boundaries resolve.

The back-button scroll jank appears to involve a second coordination issue: navigation.ts registers a popstate listener that defers scroll restoration via microtask, while app-browser-entry.ts registers a separate popstate listener that calls __VINEXT_RSC_NAVIGATE__ (which uses flushSync). The flushSync commits the incomplete tree before scroll restoration has the right content to scroll within.

These are likely two related issues (both downstream of the render mode), not necessarily one complete fix.

Relevant paths

• packages/vinext/src/server/app-browser-entry.ts — flushSync render on navigation
• packages/vinext/src/shims/navigation.ts — popstate listener, scroll save/restore
• packages/vinext/src/shims/link.tsx — <Link> also calls __VINEXT_RSC_NAVIGATE__

Expected behavior

• Client navigations keep old UI visible until new content is fully resolved (no Suspense fallback flash)
• Back/forward restores scroll only after the destination UI is ready to present
• Matches Next.js App Router behavior

Actual behavior

• Suspense fallbacks are visibly committed during client navigation, producing a multi-stage flash
• Back/forward scroll restoration fires on incomplete content, producing a visual stutter

Happy to help with a minimal standalone repro if useful.

[NathanDrake2406]

This is on new version. @southpolesteve happy to help on this when you're done refactoring

[NathanDrake2406]

actually i think browser-entry is done I'll just fix it

[southpolesteve]

Yeah feel free. I am getting near the end of the refactor I was planning on doing. My hope is this makes things easier going forward. Right now AI is struggling with the massive template strings on a couple of my branches.

[NathanDrake2406]

Yeah feel free. I am getting near the end of the refactor I was planning on doing. My hope is this makes things easier going forward. Right now AI is struggling with the massive template strings on a couple of my branches.

I've been running 5.4 high for 45m and it still hasn't figured it out. There's progress tho. Tough one to crack

[southpolesteve]

@NathanDrake2406 want to see if this PR fixes the flash for you #647

I did some manual verification and I am not seeing a flash

[NathanDrake2406]

It's still janky.
Here are videos comparison. It's subtle and kind of nitpicky but it's quite offputting for someone as obsessed about UX as I am. Prod version is just more tasteful even tho it's slower since cache missed
This PR:

CleanShot.2026-03-23.at.01.17.43.mp4

Prod (16.1.7, opennext)

CleanShot.2026-03-23.at.01.18.34.mp4

The PR I'm working on (somehow it's 2k lines lmao)

CleanShot.2026-03-23.at.01.22.00.mp4

[NathanDrake2406]

Hey @james-elicx @southpolesteve, sharing some research findings here. Claude did this research by reading through the Next.js source code (specifically segment-cache/navigation.ts, layout-router.tsx, app-router-instance.ts, and use-action-queue.ts).

Why the flash happens

The core issue is that vinext replaces the entire RSC tree on every navigation. When the full tree is swapped, every element re-mounts, every CSS animation replays, and Suspense boundaries can briefly flash their fallbacks before content resolves. No amount of client-side animation suppression or response buffering fully fixes this because the DOM elements are literally being destroyed and recreated.

How Next.js avoids it

1. Segment-level caching, not page-level

Next.js has a CacheNode tree that mirrors the route segments (layouts, templates, pages). On navigation, it diffs the old and new route trees and only swaps the segments that actually changed. Unchanged layouts keep their DOM nodes. No re-mount, no animation replay, no flash.

2. Single startTransition wrapping the reducer

Next.js wraps the entire navigation dispatch in one startTransition. The reducer returns the new AppRouterState (sync for cache hits, Promise for cache misses). React suspends on the Promise and keeps the old UI visible. There is no second nested startTransition inside the render path.

3. useDeferredValue for prefetch-to-dynamic transitions

layout-router.tsx does useDeferredValue(cacheNode.rsc, resolvedPrefetchRsc). React renders the prefetched static shell first, then smoothly transitions to the dynamic data. This is why Next.js navigations feel smooth. The static parts appear instantly, and the dynamic parts fill in afterward.

4. Never blocks on pending prefetches

From their source comment: "Don't bother to wait for a prefetch response; go straight to a full navigation that contains both static and dynamic data in a single stream." If a prefetch hasn't settled, they fire a fresh request immediately. (We found that vinext's consumePrefetchResponse was awaiting pending prefetches, which caused Firefox navigation to hang on Cloudflare Workers.)

5. useInsertionEffect for URL updates

Next.js pushes history in useInsertionEffect (fires before layout effects, before paint). This is earlier in the commit cycle than useLayoutEffect.

What this means for vinext

The flash fix likely needs a CacheNode-style tree that diffs route segments on navigation instead of replacing the whole RSC tree. That is the same architecture Next.js uses in layout-router.tsx + segment-cache/navigation.ts. The other issues (response buffering, prefetch timing, transition nesting) are symptoms of not having segment-level diffing.

@james-elicx what do you think? Is segment-level caching on the roadmap, or is there a simpler path to avoid the full-tree replacement?

For reference, PR #643 has fixes for some of the secondary issues (shallow routing reactivity, Firefox prefetch hang, server action redirect deadlock) that are valuable regardless of the flash fix.

[NathanDrake2406]

@southpolesteve I've got this idea, do you think making an eval that provides strong feedback and then run a Pi-autoresearch loop to implement this segment caching feature will work? I went a bit deeper into the rabbit holes yesterday and it turns out that segment caching is quite a complex feature, main reason why nextjs feels so good