#usePreloadedAuthQuery causes UI flash that usePreloadedQuery doesn't

1 messages · Page 1 of 1 (latest)

half pathBOT
#

Hi @plush wren. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

You’ve run into exactly the gap that usePreloadedAuthQuery was introduced to cover, but your setup (SSR + initialToken) already closes that gap in practice.

From the migration notes:

  • usePreloadedAuthQuery is described as a drop‑in replacement for usePreloadedQuery that “ensures server rendered data is rendered until authentication is ready.” [Migrate 0.10]
  • The Better Auth Next.js guide shows the standard pattern: preloadAuthQuery in a server component, then usePreloadedAuthQuery in a client component. [Next.js guide]

Separately, the Convex docs for usePreloadedQuery say that it:

  • Initially returns the server-fetched result, then
  • Switches to the client-fetched result once the client subscription is live. [usePreloadedQuery; Next.js SSR]

There is also a known class of issues where auth isn’t ready at hydration time, causing a brief “flash” or auth error when the client re-subscribes, and the recommended workaround is to “hold preloaded results in client state to render until client auth resolves.” [AuthKit race; Better Auth example]

However, the knowledge sources:

#
  • Do not document the internal behavior of usePreloadedAuthQuery beyond the high‑level intent.
  • Do not state any additional guarantees or edge‑case handling beyond “render until authentication is ready.” [Migrate 0.10]

Given that:

  • You are already:
    • Preloading with auth on the server (preloadAuthQuery),
    • Passing an initialToken into ConvexBetterAuthProvider so the client has a token immediately, [Pass initial token]
    • And all pages are server‑side protected,
  • And usePreloadedQuery is explicitly designed to hydrate from the preloaded payload and then become reactive,

the knowledge sources do not indicate any additional safety or correctness guarantees that usePreloadedAuthQuery would provide over usePreloadedQuery in this specific configuration.

So, based on the docs we have:

  • It is plausible and consistent that usePreloadedQuery is safe in your setup and that the flash you see with usePreloadedAuthQuery is an implementation detail / bug of that helper.
  • But the sources do not explicitly confirm that “usePreloadedQuery is the recommended choice when using Better Auth + initialToken,” nor do they enumerate edge cases where usePreloadedAuthQuery would behave differently.

Because of that, I can’t definitively say “there are no edge cases you’re missing” from the docs alone.

If you want to stay strictly within documented patterns:

#
  • The “official” Better Auth pattern is still preloadAuthQuery + usePreloadedAuthQuery. [Next.js guide]
  • The flash you’re seeing matches the class of issues the team is actively iterating on (auth readiness vs. preloaded data). [AuthKit race; WorkOS thread]

Given the lack of explicit guidance in the sources, the most accurate recommendation I can give is:

  • Using usePreloadedQuery in your setup is consistent with Convex’s core SSR API and with how preloaded queries are meant to hydrate.
  • The knowledge sources do not document any Better‑Auth‑specific edge case that would make this unsafe, but they also don’t explicitly endorse this substitution.
  • If you want a definitive answer beyond what’s in the docs, you’d need to raise this in the Better Auth / Convex Discord so the maintainers can confirm whether usePreloadedAuthQuery currently adds any behavior you’d be missing in your exact configuration.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: