How to wait for auth check in beforeLoad hooks after router.invalidate?

[allan-cannon]

We use beforeLoad hooks as route guards to ensure user authorization before showing route components. When certain user authorization characteristics change, we need to rerun these beforeLoad methods to make sure the user is authorized and also invalidate the queries so the data reflects the new authorization.

The problem I keep running into is when the user auth changes from authorized to not authorized, I can't figure out how to invalidate the router and the queries in such a way that the query in the route component isn't run before the beforeLoad method redirects.

For example, for this component I don't want to fetch the residency data if the user does not have access to the residency feature because that will cause an error.

export const Route = createFileRoute('/_appLayout/residency')({
  beforeLoad: async ({ context, location }) => {
    // check if user has feature
    const hasFeature = await queryClient.fetchQuery(hasResidencyFeatureQueryOptions);

    // redirect if user does not have feature
    if (!hasFeature) {
      throw redirect({
        to: '/feature-unavailable',
        search: {
          featureType: 'Residency_Module',
          redirect_url: getRedirectUrl(location),
        },
      });
    }
  },
  loader: ({ context }) => {
    // This will throw an error if called when user does not have access to residency feature
    void context.queryClient.prefetchQuery(residencyDataQueryOptions);
  },
  component: () => {
    // This will throw an error if called when user does not have access to residency feature
    const {data} = useQuery(residencyDataQueryOptions);

    return <ResidencyDataView data={data} />
  },
});

When user auth changes from residency feature enabled -> disabled, we run router.invalidate() and queryClient.invalidateQueries(), but this causes the residency data query to be called immediately even though the beforeLoad hook hasn't finished executing yet. I've tried a few different iterations of this sort of thing, but all of them result in the query being fetched before the beforeLoad hook has finished execution.

I thought this would work:

await queryClient.invalidateQueries({ refetchType: 'none' });
await router.invalidate();

But the route component is rendered before the beforeLoad method can redirect, causing our error component to briefly be shown on the screen before the redirect occurs.

This happens specifically when the user transitions from authorized -> not authorized, I assume because the route component stays mounted during the transition. If you navigate to the page directly, the component is not mounted at all, as expected.

Is there any way to invalidate the router in such a way that it will unmount the component and then not remount until after the beforeLoad method finishes execution?

[DucMinhNe]

yeah this is the missing piece: plain router.invalidate() marks the matches invalid: true but it leaves their status as success, so the current match stays resolved and keeps rendering its component (and your useQuery fires) while load() re-runs beforeLoad in the background. that's the brief flash you're seeing.

what you want is to push the matches back into pending so the component unmounts until beforeLoad finishes:

await router.invalidate({ forcePending: true })

forcePending resets matched routes to status: 'pending' and clears their error, so on the re-run the route shows its pendingComponent instead of the stale component, and your redirect in beforeLoad gets to run before anything renders. (you can confirm in the source: invalidate only flips status to pending when forcePending is set or the match is already in error/notFound, otherwise it just sets invalid: true and the old resolved match keeps rendering.)

so the order that worked for me:

await queryClient.invalidateQueries({ refetchType: 'none' })
await router.invalidate({ forcePending: true })

the refetchType: 'none' keeps react-query from kicking off the residency fetch on its own, and forcePending makes sure the component is gone (pending) before beforeLoad decides to redirect. checked against @tanstack/react-router 1.171.

[allan-cannon]

Wow I had no idea that forcePending option existed, that's exactly what I needed! Thank you so much!

I see it now in the api documentation but Claude didn't know about it and it's not in the data mutations documentation so I totally missed it.