[Documentation] Expand "Authenticated Routes" example to include async auth

[jtannas]

TL;DR

Change isAuthenticated in the docs from boolean to boolean | undefined or something else that reflects a loading state. Adjust code to be appropriate.

The only way I've found to make it work is through a custom useUser() => User hook but I'd love to know if there's a correct way to do it with Router context. Unfortunately the documentation example breaks pretty badly when trying this.

Explanation of the Problem

The docs all treat authentication as a boolean state.

export interface AuthContext {
  isAuthenticated: boolean
  login: (username: string) => Promise<void>
  logout: () => Promise<void>
  user: string | null
}

Unfortunately in client side code we have also have to deal with isAuthenticated: undefined while we asynchronously load the authentication from a server.

eg. from the Clerk types:

type UseUserReturn = {
    isLoaded: false;
    isSignedIn: undefined;
    user: undefined;
} | {
    isLoaded: true;
    isSignedIn: false;
    user: null;
} | {
    isLoaded: true;
    isSignedIn: true;
    user: UserResource;
};

This causes a significant issue with the recommended auth pattern of using beforeLoad.

// routes/_auth.tsx
  beforeLoad: ({context}) => {
    if (!context.auth.isSignedIn)
      throw redirect({ to: '/sign-in', search: { redirect: location.href } })
    return { auth: context.auth }
  },

This will cause the user to be redirected to the sign in page while the auth is still loading. I'd consider this inappropriate to do unless the user is known to be signed out, but we also don't want to let them proceed to the authenticated page.

They then hit the beforeLoad on sign-in.tsx

// routes/sign-in.tsx
  beforeLoad: ({ context, search }) => {
    if (context.auth.isSignedIn)
      throw redirect({ to: search.redirect })
  },

The auth will still be loading, so the throw redirect is not triggered.

Shortly after the auth will be loaded.
This can lead to a signed-in user sitting on the loaded /sign-in page. They've already passed the beforeLoad, so there's nothing to trigger the redirect. It's possible to hack around it with useEffect or something similar but it's ugly.

Evidence of Need

• I just spent 5 hours on it
• How to check asynchronously user status in `beforeLoad`? #1668
• Authenticated Router & Context #4018
• Contexts and Authenticated Routes deeper in the route tree #2032
• Examples using tanstack router + query with auth #1092
• How to populate context with fetch results #2094
• Route is not reloading when router context is updated #1329
  (and probably more but I think the point is made)