refactor: move auth side effects from React lifecycle to router loader via RootRouteContext

[IzumiSy]

Motivation

AuthProvider previously used useEffect to handle three auth-related side effects:

1. OAuth callback handling (handleCallback) — processing the ?code= parameter on redirect back from the OAuth provider
2. Auth status check (checkAuthStatus) — verifying the current auth state on initial load
3. Auto-login (autoLogin) — triggering login() when the user is unauthenticated

This caused a concrete problem under React strict mode, where useEffect is intentionally invoked twice during development. This meant handleCallback could be called multiple times for the same OAuth code, leading to unpredictable behavior.

Beyond the strict mode issue, running auth side effects inside useEffect has an inherent timing problem: because effects run after rendering, the component tree briefly renders in an unauthenticated state before the auth check completes. Moving these operations to a react-router loader — which runs before any rendering — eliminates this flash and makes the auth initialization more predictable.

Design

RootRouteContext — decoupling router from auth internals

The central design decision is the introduction of RootRouteContext (root-route-context.tsx), a generic injection point for the router's root route. This context carries two hook points:

loader runs  ──▶  rendering starts  ──▶  wrapComponent applied
(pre-render)       (React lifecycle)      (render phase)

• loader (URL) => Promise<Response | null> — executes in the react-router loader phase before any component renders. AuthProvider uses this to run handleCallback, checkAuthStatus, and autoLogin.
• wrapComponent (children) => ReactNode — wraps the root route element during React's render phase. AuthProvider uses this to render the guardComponent (showing a loading/login UI while auth is pending).

These two are independent concerns that happen to share a delivery mechanism: both need to be injected into the root route by an external provider.

Why a separate context?

The router (router.tsx) does not import from auth-context.tsx. It only consumes RootRouteContext, which exposes a generic loader function and a wrapComponent callback — no auth-specific types. This means:

• The router has zero knowledge of EnhancedAuthClient, AuthState, or any auth internals
• AuthProvider builds the complete loader (with all auth logic) internally and provides it via RootRouteContext.Provider
• The AuthGuard component (which reads useAuth() to decide whether to show the guard UI) lives in auth-context.tsx, not in the router

This separation keeps the router purely concerned with route construction and makes the auth integration a plug-in that works through a well-defined interface.

Single-provider limitation

RootRouteContext currently supports only one provider (a single createContext holds one value). Today the only provider is AuthProvider. If additional providers need to inject root-route behavior in the future, a composition mechanism would be needed. This trade-off is documented in the code.

No Public API Changes

All public exports (AuthProvider, useAuth, createAuthClient, guardComponent prop, etc.) remain unchanged. This is a purely internal refactoring.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@tailor-platform/app-shell@155

npm i https://pkg.pr.new/@tailor-platform/app-shell-vite-plugin@155

commit: 524751d

[IzumiSy]

/review

[github-actions]

Generated by API Design Review for issue #155

[github-actions]

[1/2 — Medium] URL cleanup after OAuth callback relies on an undocumented/untested assumption

The old code explicitly cleaned ?code= and ?state= from the browser URL after handleCallback:

const cleanUrl = buildCleanOAuthCallbackUrl(new URL(window.location.href));
window.history.replaceState({}, "", cleanUrl);

This PR removes it with the comment "handleCallback() internally cleans up the OAuth-related query parameters from the URL". However:

1. The new tests removed the replaceStateSpy assertion — so this assumption is no longer verified.
2. If @tailor-platform/auth-public-client's handleCallback does not call window.history.replaceState, the URL bar will continue to show ?code=xxx&state=yyy after the OAuth redirect is handled. More critically, because react-router re-runs the loader on every navigation, a stale ?code= in the URL could cause handleCallback to be re-invoked on the next route change with an already-consumed code, likely resulting in an error.

Recommendation: Either (a) add a test that verifies URL cleanup happens after OAuth callback (e.g. assert window.location.search is clean), or (b) restore the explicit window.history.replaceState call here as a defensive measure, independent of what handleCallback does internally.

[github-actions]

[2/2 — Medium] autoLogin: true no longer reacts to session expiry during active use

The old useEffect subscribed to [authState.isReady, authState.isAuthenticated]. This meant that if a user's session expired mid-session (the client emits a new state with isAuthenticated: false), client.login() would fire reactively and redirect them to the identity provider.

The new loader-only approach only evaluates autoLogin when a route transition occurs (loader re-run). If a session expires while the user is idle on a page, useSyncExternalStore will update authState and AuthGuard will render guardComponent(), but client.login() will never be called — the user is left stuck on the guard UI until they navigate somewhere.

This is a silent behavioral regression for apps relying on autoLogin: true to maintain uninterrupted sessions.

Recommendation: Add a useEffect in AuthProvider (or inside AuthGuard) that watches authState.isAuthenticated and calls client.login() when autoLogin is enabled and auth is lost after the initial load:

useEffect(() => {
  if (!props.autoLogin || !authState.isReady || authState.isAuthenticated) return;
  client.login();
}, [authState.isReady, authState.isAuthenticated, props.autoLogin, client]);

This preserves the original reactive behavior while keeping the loader responsible for the initial auth check.