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]

Assuming this is TanStack Start, ssr: false is the client-loader equivalent you need:

const modules = import.meta.glob('/src/content/*.mdx')

export const Route = createFileRoute('/posts/$slug')({
  ssr: false,
  loader: async ({ params }) => {
    const load = modules[`/src/content/${params.slug}.mdx`]
    if (!load) throw notFound()
    return load()
  },
})

With ssr: false, beforeLoad, loader, and the route component do not run on the server, so the MDX module is never serialized. Client navigations wait for the loader before committing the route. ssr: 'data-only' does not solve this because it still runs and serializes loader data on the server.

The unavoidable difference is the initial request: Start must render a pending fallback until hydration for an ssr: false route. For later client navigations, pendingMs controls when that fallback appears and pendingMinMs prevents a quick flash. See Selective SSR and loader pending behavior.

[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.