Client-only Loader

[futursolo]

Currently, loader needs to return serializable data. However, there are always a need to load data that is not serializable and that can result in a serialisation error.

For example:

loader: async ({ params }) => {
  // Other data loading...
  const { default: Content, frontmatter } = await import("@/content/${params.slug}.mdx");

  return { Content, frontmatter /* ...other data */ }
}

In this case, the import is not able to be sent from server to client during SSG. It can load within 1 second and should be ready when the navigation happens.
But if the import is initiated at the client side and handled with <Await>, a fallback will still be shown and flashed pretty quickly.

I tried all kinds of ways to make it work so that the navigation will happen when Content is loaded, but none of the ways will allow this behaviour.

This makes me feel that a react-router equivalent of clientLoader is helpful in this context.

[schiller-manuel]

this needs more context. i assume you are using TanStack Start, not just Router. Are you using ssr: 'data-only' ?

[futursolo]

No, I am not using data-only. Yes, I am using Tanstack Start.

After playing around it a little bit more, I suspect it might have something to do with #289.

I have made an example repository.

See: https://github.com/futursolo/router-data-loading-example

It has 3 packages:

rr-expected: React Router with expected results
tanstack-actual: Tanstack Start with working results
tanstack-expected: Tanstack Start with expected results

In rr-expected, when Go to Post abc is clicked, when the navigation happens, the content is ready.
In tanstack-actual, when Go to Post abc is clicked, when the navigation happens, the content flashes with Loading...
In tanstack-expected, when Go to Post abc is clicked, when the navigation happens, the content is ready. However, if you refresh the page when currently viewing /posts/abc, it crashes because the server cannot serialize a function.

I am willing to settle with any way that can:

1. Let vite render the MDX files (MDX files have React component imports with aliases).
2. When navigation happens, It doesn’t flash with Loading... unless network is slow (Longer than pendingMs).

Unfortunately, after one day of trying various options, I still haven’t been able to obtain the desired effect with Tanstack Start.

clientLoader can be one way to workaround it by preventing Await-ing the import when Content is available from clientLoader. clientLoader won’t be run when opening a page from SSR and SSR hydration will show the content when hydrating. So both scenario can avoid showing Loading....

However, this is still not as elegant as fixing #289 so data loading can function similar to React Router.

[lMysticl]

Correction for the prerendering requirement: my initial ssr: false suggestion does not meet the requested combination of prerendered MDX HTML, serializable loader data, and client navigation without the MDX fallback. It should not be applied as the solution to that requirement.

In the reproduction discussed in the follow-up, tanstack-actual keeps loader data serializable, but the component creates a separate MDX import promise and <Await> briefly renders its fallback. tanstack-expected avoids that during client navigation by returning Content from the loader, but direct SSR then fails because a component function crosses the server/client serialization boundary.

ssr: 'data-only' still runs and serializes the loader on the server, so it does not solve that function-serialization issue. ssr: false gives up the prerendered route content the author requires.

A workaround with different trade-offs is to make the MDX component part of the route module graph, for example by generating a route module per MDX file with a static import. An eager import.meta.glob(..., { eager: true }) also makes modules available, but bundles all matched MDX modules into the client.

The fallback behavior discussed here is related to #289 and the router-level proposal #8188. See Selective SSR for the SSR modes. The corrected reproduction analysis and its boundaries are in the linked follow-up.

[futursolo]

Thank you for the idea.

However, I do wish to do SSR during prerender. Because:

1. Some logics are unnecessarily complicated to be sent to client side.
2. Not having static HTML on these content will inevitably hurt SEO.

[lMysticl]

You're right — ssr: false does not meet the prerendering/SEO requirement, so my previous answer was incomplete.

I checked the reproduction. tanstack-actual keeps loader data serializable, but the component creates a separate MDX import promise and <Await> briefly renders its fallback. tanstack-expected avoids that during client navigation by returning Content from the loader, but then direct SSR fails because the function crosses the server/client serialization boundary.

So there is currently no route option equivalent to React Router's clientLoader that combines all three properties: prerendered MDX HTML, no function in serialized loader data, and no fallback flash during client navigation. ssr: 'data-only' does not change that. The immediate fallback is the router/external-store limitation tracked in #289; #8188 proposes a router-level fix.

The practical workaround today is to make the MDX component part of the route module graph instead of loader data — for example, generate one route module per MDX file with a static import. An eager import.meta.glob(..., { eager: true }) also works, but bundles every MDX module into the client. If neither trade-off is acceptable, the behavior needs a router-level change rather than another loader configuration.