FCP regression and pending component flashing on static pages (Next.js -> TanStack Start migration)

[aymericzip]

I am migrating the documentation website for Intlayer from Next.js to TanStack Start. All pages are fully static with no authentication barriers. Following the migration, the application experiences a ~30% regression in First Contentful Paint (FCP) and flashes the defaultPendingComponent (resulting in a black screen) on every route navigation.

It appears the routing mechanism waits for the loader to fetch data from the server before rendering the page, blocking the UI despite preloading and suspense configurations.

Screen.Recording.2026-06-08.at.7.16.36.PM.mov

Nextjs Lighthouse result:

Tanstack Lighthouse result:

Repositories & Deployments:

• Baseline (Next.js): intlayer.org | Source code
• Issue (TanStack Start): new.intlayer.org | Source code

Current Configuration & Setup:

• Prerendering: Enabled.

• Hydration: No hydration errors present.

• Code-splitting: The first section of the landing page is statically imported. The subsequent sections and documentation navbars are optimized using lazy imports to isolate the initial paint.

• Suspense: Boundaries are configured.

• Router configuration (/src/router.tsx):

• defaultStaleTime: Infinity

• defaultPendingMs: 0

• defaultPreload: 'intent'

• Navigation links: Set to preload: 'viewport'.

Loader Implementation Example:
The issue is most prominent on the documentation pages. Below is the current setup for the catch-all docs route, which fetches the markdown content and navigation data concurrently:

// /src/routes/{-$locale}/_docs/doc/$.tsx

export const Route = createFileRoute('/{-$locale}/_docs/doc/$')({
  loader: async ({ params }) => {
    const { locale = defaultLocale } = params;
    const slugsStr = params['*'] || '';
    const slugs = slugsStr ? slugsStr.split('/') : [];

    const [result, navData] = await Promise.all([
      loadDocPage({ data: { locale, slugs } }),
      loadNavData({ data: { locale } }),
    ]);
    
    return { result, navData };
  }
})

Hypothesis & Feature Request:
The core problem seems to be the absence of a direct generateStaticParams equivalent in TanStack Start for fully static build-time data retrieval. The loader executes and blocks the UI transition instead of instantly serving pre-computed static data.

Are there specific configurations missing to force pure build-time data fetching and instant client-side transitions for static routes, or is this a current limitation of the framework's prerendering architecture?

--

CC @tornado-softwares

[tornado-softwares]

Hey,

I had started noting things down on Discord, i'm putting them here to keep a record of the issue.

• [Cause 1] I noticed that your project uses Shiki, and that Shiki requires another library to support Wasm on Vite, which adds 600kb of JS. So i'm going to try migrating this to PrismLight using react-syntax-highlighter

• [Cause 2 (Maybe)] Then I noticed that your styling was manually imported using rel=stylecheet, so the browser fetches it first and applies it immediately. I'm not sure what to do about this, but there's quite a bit of documentation to read (https://tanstack.com/start/v0/docs/framework/react/guide/css-styling), so I'm noting it down here.

• [Not a cause] There's a huge unmerged_dictionaries file of about 1900KB that's fetched from the doc page. I understand it's necessary for the playground feature, but the fetch seems to be initiated by a preload-helper so I don't think it's something that directly slows down the page. But I'll make a note of it anyway.

TW: I've only analyzed the bundles so far; I'll try to look into prerendering as well. It's strange because in React Router, the loaders are included in the prerender.
So, you're saying the loader runs even with prerendering on TanStack, if I understand correctly?
Actually, I did a quick check with and without prerendering, and the performance on Lighthouse didn't change much.

[tornado-softwares]

Re (Cause 1)

I was able to implement the code blocks with React Syntax Highlighter and so remove the shiki.css + the vite-plugin-wasm (600kb).

I delegated this task to a AI to save time but the themes are rather ugly. A couple of things need fixing, but it works, and I gained about 10 points of performance on Lighthouse Desktop (70 -> 80) Mobile (30 -> 40). Nevertheless, this hasn't changed anything for the FCP time.

NB: Never use AI, Never use shiki :)

[aymericzip]

Hey @tornado-softwares,

You're right about Shiki. I used to use PrismLight with react-syntax-highlighter about 2 years ago, but I wasn't satisfied with the results and switched to Shiki. The library is lazy-loaded, so it shouldn't have any impact on FCP. But I'm definitely open to any optimization suggestions on that front as well

The same applies to unmerged_dictionaries. It's indeed needed for the editor, but it's also loaded dynamically

[aymericzip]

Pin: TanStack/router#7630