[feature request] Ability to wait until client is ready

[jamesarosen]

@workos/authkit-react uses a natural React interface:

const { isLoading, user } = useAuth();

This works great for typical React components.

It doesn't work very well with frameworks like Tanstack-Router and React-Router that have lifecycle hooks for fetching data that run before the component renders.

It would be really nice to be able to do this:

export const Route = createFileRoute('/authenticated')({
  async beforeLoad({ context }) {
    const { clientReady } = context.auth; // the result of useAuth
    return clientReady.then((user) => {
      if (!user) {
        throw redirect({ to: '/auth/login' });
      }
    });
  },

  component:() => {
    const { isLoading, user } = useAuth();
    return "isLoading is never true here. User is always a user";
  },
});

[jamesarosen]

One might think to use the getAccessToken() Promise:

export const Route = createFileRoute('/authenticated')({
  async beforeLoad({ context }) {
    const { getAccessToken } = context.auth; // the result of useAuth
    return getAccessToken.catch(() => {
      throw redirect({ to: '/auth/login' });
    });
  },

  component:() => {
    const { isLoading, user } = useAuth();
    return "isLoading is never true here. User is always a user";
  },
});

But that doesn't work because the underlying implementation of getAccessToken gets rewritten when createClient resolves. Before that, it's a function that always returns a rejected promise. And beforeLoad doesn't get re-called when createClient resolves.

That approach would work if NOOP_CLIENT.getAccessToken() returned a promise that stayed unresolved until authentication succeeds (resolve) or fails or times out (reject).

[jamesarosen]

Another option, inspired by the Tanstack-Router Firebase example is to render a loader until isReady is true:

// main.tsx

function AppWithAuth() {
  const auth = useAuth();

  if (auth.isLoading) return <>Loading…</>;

  return <RouterProvider router={router} context={{ auth }} />;
}

Now the async loaders are at least guaranteed that the auth implementation is the real one.

The downside is substantial layout shift.

[jamesarosen]

An additional gotcha: onRedirectCallback can fire before isLoading=false. If you want to pull off state.returnTo and trigger a navigation, you need to be careful to do it after isLoading=false. Otherwise, you can get into an infinite loop:

1. user is unauthenticated
2. user goes to /needs/auth
3. wait for isLoading=false
4. gate sees auth.user == false, calls auth.signIn({ state: { returnTo: '/needs/auth' } })
5. user performs auth flow
6. user is sent back to /auth/callback?state={returnTo:/needsAuth} (modulo encoding)
7. onRedirectCallback picks up returnTo, sends user to /needs/auth
8. auth is still { user: null, isLoading: true }, so gate sees auth.user == false and calls auth.signIn(...)

This requires a slightly awkward dance:

let returnTo: string | null = null;

function onReturnTo({ state }) {
  const returnTo = state?.returnTo;
  validateReturnTo(returnTo); // prevent open redirect, infinite loops
}

function AppWithAuth() {
  const auth = useAuth();
  if (auth.isLoading) return <>Loading…</>;

  useEffect(() => {
    if (returnTo == null) return;

    router.navigate({ to: returnTo });
    returnTo = null;
  }, [auth.isLoading, auth.user])

  return <RouterProvider router={router} context={{ auth }} />;
}

[nicknisi]

Hey @jamesarosen, I'm taking a look at this. Quick question about your architecture: Are you using TanStack Start (SSR) or TanStack Router in a client-side SPA?

If you're doing SSR, our TanStack Start SDK handles auth in server middleware, which avoids this timing issue entirely.

[jamesarosen]

This app is a pure SPA with TanStack-Router, not TanStack-Start.