Catalog / showcase of possible use cases?

[lintonye]

Is there a plan to include a page that lists possible use cases for all the concurrent features / patterns? The examples in the current docs are super helpful but I believe it'd be useful to include some more polished examples that:

• are more "real-worldish" (or even better than the status quo),
• highlight what Concurrent React is capable of
• highlight the fact that the supported improvements are relatively low-hanging fruits, compared to expensive one-off solutions

Why?

To help designers understand Concurrent React in a more realistic context.

As far as I can see, Concurrent React is very relevant to design, and it should be something that designers are aware of so that they could collaborate with engineering to build the best experience possible.

Also, I think it's generally useful to visualize why it's worth it to go the extra mile to add fine-grained UI improvements such as progressive loading states.

A bit of my background: I've spent the recent couple of years on helping designers understand React. Unlike us developers, most designers don't have the time or skills to learn all the nuances of React -- they have design work to finish too. My focus has been going through all the React topics and pick those that are directly related to design. Usually it's about React fundamentals that would allow a designer to read the JSX code, style it, animate it etc. But Concurrent React seems like the first advanced feature that they'd need to be aware of -- at least what it is capable of.

Does this look like something we could create and maintain as a community? I'd love to contribute to it.

PS: To be honest, I myself have been putting off learning Suspense until now (just finished reading old docs and discussion posts here. They are great!). That's partly because I wanted to keep my mind "fresh" when it's time to write about Suspense. But that's also because I had an impression that Suspense was just icing on the cake that only big corps can afford. A good showcase of its capabilities in combination of its ease of use would give me the motivation.

[alvarlagerlof]

I think this might be covered in the new docs? Or maybe you're talking about demos more?

[lintonye]

yup in the new docs would be great, as long as it exists somewhere and it's easy to find.

[rickhanlonii]

We'll also be posting about the new concurrent features to the workgroup soon, but I think something separate that shares what we've learned in our research about UI loading-state and refetching patterns would be useful as their own posts 👍

[gaearon]

Like @acdlite noted below, it won't be the focus of the new docs initially because we're busy explaining things like State at this moment, and haven't even gotten to Refs or Effects yet. Eventually it would be integrated but I think some examples earlier that are separate would be nice.

[acdlite]

I personally would love for this to exist. We've talked about it for years but haven't invested the time.

AFAIK this isn't currently a priority for the new documentation website, whose initial focus is on explaining concepts from first principles. But I totally agree on the need for real world examples. We've sometimes referred to these as "recipes" since you should be able to copy-paste-tweak the patterns.

Community-built would be good, though I would prefer for the React team to maintain editorial control so people have confidence that anything we publish there is endorsed as a best practice.

[markerikson]

Y'know, this sorta relates to the "React Community Tools and Practices" site I've been wanting to get off the ground:

• Initial RFC: Scope and Goals markerikson/react-community-tools-practices-cheatsheet#1
• https://react-community-tools-practices-cheatsheet.netlify.app/state-management/overview/

[gaearon]

But that's also because I had an impression that Suspense was just icing on the cake that only big corps can afford.

I'm curious to hear more about what you mean by this. It's a mechanism to coordinate data loading declaratively — what created the "big corp" perception? Here's a 50-line example using Suspense: https://codesandbox.io/s/keen-herschel-8cxjt?file=/src/App.js

are more "real-worldish" (or even better than the status quo),

One difficulty here is that you really only see the "overall effect" of the feature when the UI is realistically complex, but at that point, the example is no longer simple enough to follow in isolation.

But overall I agree that this is the most "designer-oriented" suite of features we've worked on, and they need to be introduced with a similar designer-oriented mindset.

[tesseralis]

I think the intention was that at this stage (alpha) we’d like to focus on the library maintainer community since you can’t adopt any new features in the app until the libraries you use are compatible.

Ah, yup, that's where the miscommunication was. So to be clear:

1. concurrent features, such as the Suspense API are intended for use by app developers (even without libraries?)
2. currently the react team is focusing outreach for library maintainers because concurrent features need to be enabled for them before app developers using those libraries can use them.

Is this correct?

[gaearon]

Yes. (I’d even say they’re mostly intended for app use because they’re about orchestration — and libraries don’t know how the app developers want to orchestrate things.)

[lintonye]

With that approach, loading indicators can become a first-class concept for design tools. You can imagine something like Framer having a built-in way to specify a placeholder for any part of UI, which, once added, would be compatible with any React data fetching (or code splitting) solution.

Yup. I totally realized that after reading the docs. It's just there's perhaps a better way that'd demonstrate the benefits sooner.

Can you go into more detail on which part of the syntax is awkward?

I think it was mainly due to the inertia of the old knowledge that I was used to. Also the unfamiliarity of the words ("Suspense" and "fallback") played a part. "Wrapper" and "loading" would have been easier to understand (but I'm not suggesting to replace them!).

Seeing <Suspense> in JSX feels very different than seeing <div> or <Header> there. People would need to acquire a new mental model for that. The tricky thing is how to teach a good enough mental model without diving too deep into how things work: interruptible rendering, fetch-as-you-render etc. After all, arguably the word "Suspense" includes a bit of implementation details.

[sylwiavargas]

Thank you @lintonye for voicing these thoughts -- they align with the comments I got from devs at meetups, the instructional staff, and my students when Suspense was first introduced. Mainly, I heard these points numerous times:

• "And all it offers is to add a loading indicator in a different, arguably more awkward syntax? Why don't we just use the good old conditional rendering for that?"
• The perceived difficulty and (perceived) lack of easy-to-see benefits are the source of my impression
• Also the unfamiliarity of the words ("Suspense" and "fallback") played a part.

I also put off reading the docs or implementing Suspense for a long time because of the "inertia of the old knowledge" you mentioned -- and because of the fact that more experienced devs seemed to view it as a gimmick.

So perhaps revising our mental model could be a good place to start talking about how concurrent features can be presented to the general public. In this way, maybe it would be less easy for folks to play it down as a "gimmicky loader".

EDIT: Also, I'm a little late to the party but I've just seen #28 and I found it immensely helpful (and relevant in this conversation)!

[gaearon]

I wanted to add that we've just posted a deep dive on the role of <Suspense> with server rendering. It goes quite deep but I hope it's more or less approachable and helps explain some of the less obvious benefits of declarative loading indicators: #37.

[tesseralis]

Seconded that examples of the use-cases that concurrent features are supposed to fix would be useful. I'm guessing that the examples in the current documentation are still valid for the updated API and can serve as a starting point? Once enough documentation gets released to get started I'd love to try my hand at making some demos :)

[gaearon]

Yes, they’re still relevant. It’s just that each feature is a bit more generic than the examples on that page may show.

For example, startTransition works both for IO work (suspending on network) and for CPU work (showing pending indicator for an expensive re-render). Same for useDeferredValue. Here’s the updated demo from my JSConf Iceland talk with startTransition: facebook/react#21401

The main changes since the API docs were written are:

• Removal of the options/timeout argument (all transitions for “existing” content are “infinite” now)
• Flipping useTransition return order
• Adding top-level React.startTransition export
• A lot of bugfixes

See more about startTransition: #41