Bug / Docs / Question: Handling interrupted suspense boundaries

[jacob-ebey]

In a world where portions of the component tree can hydrate and become intractable with child components still being suspended, does documentation / guidance exist on how to handle these cases?

Example: https://simple-remix-deferred-demo.fly.dev/

Green: Hydrated
Red: Suspended

Clicking either of the "Link" elements in the hydrated portion of the page, this will trigger a re-render and causes the suspense boundary to receive an update before it finishes: https://reactjs.org/docs/error-decoder.html/?invariant=421 This isn't an issue in terms of app functionality as implemented as I was under the assumption parent updates from interactive components would be expected, I mean, why wouldn't they?

So I guess there are a few questions I have:

1. Why does react log this error? Is it an actual error?
2. Are there implications I can't think of that would cause your average bare bones suspense usage to fall over and that's the reason this message exists?
3. When you expect updates to happen when boundaries are still suspended, is there a documented way to handle this to avoid this message?

[gaearon]

Is there a sandbox reproducing this? Ideally without a framework.

[jacob-ebey]

I could get you one later. It's simple though:

SSR and suspend. Before suspense boundary resolves, hydrate the parent component and set state.

[jacob-ebey]

Here ya go: https://github.com/jacob-ebey/react-suspense-reproduction

steps:

• clone
• npm i
• npm start
• load page and click button when boundary is suspended to see message in console

[jacob-ebey]

@gaearon, friendly ping on this, happy to provide more information if needed. This seems like a common case to me and would love to figure out how to handle this so users don't see a scary error message in the terminal.

[jacob-ebey]

Do we need another equivalent of suppressHydrationWarning for <Suspense>?

[tom-sherman]

For prosperity, there are two ways to suppress the warning that I know of:

1. Use startTransition: tom-sherman/react-suspense-reproduction@24388fc
2. Memoize the suspense boundary so that the state update doesn't cause it to rerender: tom-sherman/react-suspense-reproduction@ebcdeb6

[tom-sherman]

From #24082

We can go even further and allow updates at higher priority (though not sync) by implementing selective hydration at the root, like we do for Suspense boundaries: interrupt the current render, attempt hydration at slightly higher priority than the update, then continue rendering the update. I haven't implemented this yet, but I've structured the code in anticipation of adding this later.

Could your reproduction be hitting this un-implemented case?

[sebmarkbage]

I think the question is not about direction per se (the error message already tells you to use startTransition) - but why.

Why does react log this error? Is it an actual error?

Kind of. It's a "recoverable error" which is a new thing in React 18 that we need to document better how to deal with. You can customize display using onRecoverableError. It's not like an error thrown and caught by an error boundary because those are actually user visible error and the normal flow can't be rendered. It's not like console.error in DEV because those usually have a fallback behavior that might be wrong. It's something that happens where we are able to recover by rendering again but it might be subtly different or usually just bad for perf.

There's typically a way to deal with it though. It might not always be worth it. E.g. maybe it only happens if someone does a particular interaction really fast in some edge case. If it's always happening such as when you do initial render or on every navigation - then it's probably a problem you need to fix.

Are there implications I can't think of that would cause your average bare bones suspense usage to fall over and that's the reason this message exists?

We can't commit a sync update partially. On principle. To avoid things like switching a theme on the outside and not the inside and other sorts of consistency bugs. So for sync updates that suspend inside a Suspense boundary, we'll hide the content and show the fallback instead. The intention is that this should basically never happen because those updates should've used startTransition instead. In theory you could hit this code but it would be considered bad UX - but maybe not enough to warrant a warning.

For boundaries that haven't hydrated yet this hiding means that we also delete the original DOM - but tbh we shouldn't really have to and maybe we could fix that.

That said, even then it would be considered bad UX to trigger the fallback. Typically you'd delete the Suspense boundary and render something else (e.g. using proper keys), or use a transition.

When you expect updates to happen when boundaries are still suspended, is there a documented way to handle this to avoid this message?

Those should typically be wrapped in startTransition. Almost everything that isn't like a keystroke updating something very regional should be in a startTransition.

[jacob-ebey]

Take the example code-base and assume everything except these lines are hidden behind framework abstractions:

        <p>
          <button onClick={() => setCount(count + 1)}>Click me</button>
        </p>
        <React.Suspense fallback={<SuspendedFallback />}>
          <SuspendedThing />
        </React.Suspense>

In this case, the underlying "framework abstractions" never actually set state or cause a re-render. There is no re-render caused by anything except "user-code".

Are you saying that anytime a suspense boundary is potentially being rendered at or below a component performing a state update it should be wrapped with startTransition? This is where I'm thrown.

[sebmarkbage]

It's hard to talk about an abstract example because reason something should be wrapped in startTransition depends on the use case. It's not that everything should be wrapped but a lot of things should.

If setCount was a route navigation that updates almost the whole screen, or a refresh of the whole screen then it should.

If it's updating a counter as part of some form field, then maybe it don't need to.

If it's the second case then the error falls into this case:

It might not always be worth it. E.g. maybe it only happens if someone does a particular interaction really fast in some edge case.

Because the way it's meant to be used, it's likely it won't actually happen very much or even be that bad when it happens. If that was the case you probably wouldn't even file an issue because you wouldn't be able to repro it.

When something is consistently triggered, we see that it's either because it's something like a navigation that should be categorically be a transition or it's because of something that's bad for perf anyway like two-pass renderers cased by setState in useEffect.

[jacob-ebey]

Is there a reason we have to recreate the whole DOM for a suspense boundary that re-renders in a suspended state? Seems to me like that should go through the standard reconciliation process by default and not be detrimental to performance / cause this "error" to be logged.

[sebmarkbage]

I forget the reasoning but yea I noted that too. It might be outdated.

tbh we shouldn't really have to and maybe we could fix that.

That code path handles other scenarios too where we might fail to hydrate it, but I think it would make sense in theory to add a special case (more code).

Note that it would still "hide" it by triggering display: none on all the children and then reveal it again once it loads so it's still not great.