[Framework] Add a way to reload the frontend when the backend changes

[Menduist]

A mismatch between the frontend and the backend is a sure way to get unexpected crashes, and should be avoided as much as possible.

An easy way to do this is to use browser navigation instead of react-router navigation when a new version is deployed

Maybe a way to achieve this would be to enable:

declare const APP_VERSION: string;
export const middleware: Route.MiddlewareFunction[] = [
    i18nextMiddleware,
    async (_, next) => {
        const result = await next();
        result.headers.set("X-App-Version", APP_VERSION);
        return result;
    },
];

export const clientMiddleware: Route.ClientMiddlewareFunction[] = [
    async (_, next) => {
        const result = await next();
        // Currently: not possible to read headers
        // not possible to know if its a navigation or a fetcher
        if (result.headers["X-App-Version"] !== APP_VERSION && navigation.state === "loading") {
            // not possible to trigger a reload
            return browserNavigate();
        }
        return result;
    },
];

I've managed to implement something similar by using a lot of react router internals and monkey-patching fetch, but it seems like a few additions in the middleware would make this a lot easier

[rossipedia]

This has been discussed quite a bit over the years, and while I would absolutely welcome this addition, I understand that it's a very hard problem to solve in the general case.

What I think would help, and wouldn't be super difficult to implement, would be a way to supply a custom fetch function to React Router. This would allow you to inject request headers being sent to your server, as well as inspect response headers and perform necessary global actions in response, such as displaying a notification to the user that they're running an out-of-date client and giving them the option to reload.

Maybe something like:

<HydratedRouter
  // defaults to `window.fetch` if not supplied
  fetch={async (input, init) => {
    const response = await window.fetch(input, init);
    const serverVersion = response.headers.get('X-App-Version');
    if (serverVersion !== APP_VERSION) {
      window.dispatchEvent(new ClientOutOfDateEvent({detail: serverVersion}));
    }
    return response;
  }}
/>

Honestly, I'd like to see this available in all the modes where it makes sense (ie: Framework, Data, RSC).

[sergiodxa]

Aside of that, I think a hook that returns if RR detected a version difference between client and server could be useful.

You only really need a boolean and then show a banner or trigger a reload.

If that hook is readable everywhere you could even disable forms to avoid triggering an action, or store in window.sessionStorage the input data before a reload.

[Menduist]

There are two pieces to this puzzle: detecting version change, and reacting to it

To detect the change, a custom fetch, client middleware able to read/write headers or service worker are all viable options (though my personal preferences are middleware > custom fetch > service worker)

To react to it, a benefit of how "canon" react-router app are written is that a browser navigate and RR navigate should have almost exactly the same behavior to the user.
IMO, adding a way to disable the RR navigate based on some rules is a far better solution than any banner (transparent to the user, "instant", etc)
(The banner still make sense on "long running pages", but the banner is already achievable once the version change detection is in place)

---

To give some background, what we ended up doing in our application is that once a version change is detected (using the monkey-patched fetch), if the user tries to navigate to a different pathname, the custom fetch will return a X-Remix-Redirect & X-Remix-Reload-Document to trigger a browser navigation.
Finally, if an ErrorBoundary is triggered on an outdated frontend, we window.location.reload().
(After a hard-refresh we show a toaster to the user to explain it).

It seems like a very nice setup: most of the time the version updates will be completely transparent, however if a loader becomes backward-incompatible, the user will only loose its react state. And worst case, if an action becomes backward-incompatible while the user tries to use it, the action will not be processed and the page will refresh.

Though I understand each app will want different tradeoffs, so having flexible ways to detect changes, and flexible ways to preventing RR navigation would be best.

[sergiodxa]

The main issue is with actions, an action usually means a form which may have a lot of inputs

Imagine as a user you type into a text area a long content, but because in the process a new deploy happened that changes the action in an incompatible way once you submit the action fails, the page reloads and you lose the whole content you wrote

That's a terrible ux, this is why I think RR should offer a way to detect the version change, ideally as soon as it happens (polling an endpoint for example), then the app can choose how to handle it

For navigations automatically falling back to a document reload is safe, for actions you may want to do extra things like save current value in the browser web storage so you can recover it after reload, or let the user knows they need to manually reload and keep their work

[Menduist]

100% agree - though this issue is complex enough that there is no good solution at the RR level, besides allowing the version change detection, and ideally ensuring that at least when you land on the form you are at the latest version

I think handling the loader cases is already a huge step in the right direction - in our experience we've had multiple breakages of loader during deployment, and none of action.

That can be explained because :

• Most of the web interactions are GET and not actions.
• actions are generally smaller in surface area than loader (ie change this value instead of give me all the relevant state for a page).
• like many RR apps, our actions are schema-tized using zod, making any breaking change very obvious, compared to often inferred return types of loaders.

And once you have the tools to know if the frontend is outdated, you have everything you need to implement what you are proposing (a poll + banner + save & restore in web storage), but that belongs in the user app not RR imo

EDIT: but to be clear, an action breakage would indeed be far worst than a loader breakage, since the user would loose whatever they were trying to action on, instead of just loosing their react state. Just saying they are less frequent, and not fixable at the RR layer

[sergiodxa]

Agree, we should focus on a way to let you know. RR already detects on a navigation if the manifest version on client is different than server, and based on that it does a document navigation, so that's kinda solved.

It could be better tho, I think if a route module is already loaded client-side the manifest is not requested again so it won't detect issues. If RR could know as soon as it happens a new version is deployed it could make that better.

Ultimately, giving the app devs a way to know there's a versions mismatch between client and server will allow app devs to do whatever they want, e.g. you could wrap every Link/NavLink in a component that forces reloadDocument if there's a version mismatch, or you could let the user know (Discord does this) and provide a button to reload (basically window.reload()).

[brophdawg11]

Related: #14790

[brophdawg11]

Adding some details from a discussion the steering committee had a bit ago that didn't make it into here.

Jacob suggested maybe just a raw DOM event when we are going to reload. If we detected a manifest version change on navigation we'd abort the navigation, fire the event, and reload only if they didn't call preventDefault. That way they could listen for the event in a root layout, call preventDefault and setState on something that would show a little prompt to the user.

[scottcorgan]

Our use case for in this scenario is provide zero downtime deploys for our users who might be in the middle of filling out a large form.

Another use case is when users are in the middle of scrolling a very long report, they click a link that opens a child route, and the whole thing reloads and we lose scroll position. (That might be on us as well)

We originally had lazy route discovery enabled, but it would auto refresh the page while they were in the middle of the form. We disabled it so that we can manually tell our users that there is a newer version of the application available. It's been somewhat unreliable, but that's on our side.

An ideal scenario would be some way to be notified that there is a newer version of the manifest. This would need 2 things:

1. a timestamp so we can track time between new version and user actually using the new version
2. A way to send a notification to the UI to tell the user there is a new version. That would come from the proposed event.

How we get that data is not important to us. We are really interested in deploying more often, but feel we can't just yet until we are confident we aren't interrupting workflows

(I do know there's other ways around this like drafts, etc., but wanted to share our use case)

[brophdawg11]

What would the timestamp capture? Could you get that via Date.now() in the event handler?

[scottcorgan]

We have a 10 minute buffer for out deploys as caches propagate. It's not a deal breaker, just an idea.

[ZipBrandon]

Any movement on this? I'm still stuck with what I posted back in Feb. #14790

[morgan-coded]

Emit a small event immediately before the existing manifest-version reload? I'd keep reload behavior unchanged and first confirm the event name, payload, and whether it should be cancellable.