Education and course material coordination

[chantastic]

Hey friends!

Code "advent" season is around the corner!

I'm thinking about what I'll be doing for React Holiday this year and suspect that many of you are finding opportunities to write, speak, or talk about React 18.

Back in April the guidance was "don't make courses." And I'm hoping to see if that has become more nuanced as we approach React Conf and a new doc site release?

• Are there APIs and messaging that we could — at this point — safely write about?
• Is there a way we should communicate caution? ("Exploring React 18-alpha", "Preparing for React 18", etc.)

I'd love to help coordinate a list of "safe", raw topics that everyone can put their personal spin on.

Thoughts?

[cassidoo]

Thank you so much for bringing this up @chantastic, I think this is so huge! It might be useful to know some of the timing of the public beta for this, too.

It seems like the safest thing is the new Root API (which luckily isn't a big lift), are other things fairly solid?

[chantastic]

yes!

automatic batching also feels like it should be on the list. likely the biggest thing that someone would need to be aware of for a no-concurrent-apis migration.

[chantastic]

with it the escape hatch of ReactDom.flushSync

[gaearon]

Thanks for the question! I don't think we have super cohesive guidance on this since we're still deep in the development process, and aren't very close to finalizing the release yet. But I'll try to answer this.

Back in April the guidance was "don't make courses." And I'm hoping to see if that has become more nuanced as we approach React Conf and a new doc site release?

Please note that the documentation rewrite has no relation or coupling to the React 18 release. The doc site is focused on explaining the existing React patterns -- primarily, reintroducing React but with a focus on Hooks. By the time we release 18, we'll update either site (whichever is the main one at the time of the release) to match what goes out in 18, but these projects are completely decoupled.

The safest time to create any content is always after a stable release. That doesn't change. But I'll give you as much information as I have about the state of different pieces, and you can make a decision about how that informs your content strategy and what's best for community.

Note that nothing below is a guarantee, it’s just the current perception.

• 🔴 The Big Picture: We don't yet have a cohesive publicly sharable story around how all the features fit together. We have a multi-year technical vision behind all of this work, but it's not immediately obvious from looking at the individual pieces. For example, many people saw <Suspense> years ago but did not fully see its "power" until we shared New Suspense SSR Architecture in React 18 #37. There are more things like this that we haven't had a chance to write about yet. Because we haven't yet shared our "story" about what React 18 means, people creating content might be compelled to come up with their own. E.g. one common misinterpretation is that React 18 is about "Facebook-scale apps". Another common misinterpretation is that React 18 is about optimizing data-intensive applications. Some of misinterpretations are based on our own outdated messaging from when we tried to explain individual pieces several years ago, or when we emphasized things that are easy to explain over things that are important. This is just to warn you that if you try to infer the vision from individual pieces, it might contradict the vision that we will be sharing. We're not ready to share it yet because we haven't yet worked out how to communicate it, and that will become a focus after most of other work is done. So keep in mind that this is a major conceptual gap that you might encounter if you try to summarize React 18 and related work on your own.
  • ✅ The "gradual adoption" messaging is solid though and our plans there aren't changing. (What happened to concurrent "mode"? #64 works as a historical reference for people who've been following the journey.) It's more that gradual option of what and why is missing and we'll need to explain it better than the past isolated attempts.
• React 18
  • ✅ Automatic batching for fewer renders in React 18 #21 seems as "stable" as things can be in an Alpha release. This doesn't introduce new concepts (aside from explaining batching to people who weren't aware that it was happening). Seems OK to write about. I wouldn’t frame it as “preparing” for 18, it’s just an explanation of a behavior change that will hopefully make existing cases more consistent.
  • ✅ Replacing render with createRoot #5 seems like a relatively safe bet that createRoot API will stay as described, and that it will be the migration path from ReactDOM.render. However, keep in mind that:
    • 🟡 Different root methods might be added or removed. E.g. we recently removed root.hydrate in favor of top-level hydrateRoot. More changes like this may happen.
    • 🟡 The testing story with createRoot is not entirely worked out. See also Planned changes to `act` testing API #23.
  • 🔴 Context selector status and plans? #73 is not known whether it will fit into 18 or not, so it's best to assume it will come later.
  • 🔴 It is not yet clear whether RFC: Plan for custom element attributes/properties in React 19 facebook/react#11347 will be finalized by the time 18 is out, but Add custom element property support behind a flag facebook/react#22184 is in progress. Probably best not to describe it yet.
  • Strict Mode
    • 🟡 Adding Reusable State to StrictMode #19 While we don't currently plan to change how Strict Effects work, it might be better not to emphasize this until more libraries are compatible. E.g. currently Strict Effects break all Redux apps (but this will be fixed). I don't think we want people to try "fixing" their effects until a stable version is out, and they can actually use Strict Mode to find issues.
    • 🟡 Update to React Strict Mode Double Rendering #96 is a change to ergonomics but the mechanism and heuristics might still change if we find some flaws. For example, we're now working to fix Console log shows the wrong destination file  facebook/react#22257. Developer ergonomic things like this will likely be solved last overall, so don't expect a lot of polish there until Stable.
  • Library Compatibility
    • ✅ Concurrent React for Library Maintainers #70 is an accurate summary of how React 18 affects library authors.
    • 🟡 useMutableSource → useSyncExternalStore #86 is underway and is an example of why one might not want to make a course about unstable APIs.
    • 🔴 There will be more work in this area, like [Experimental] Add useInsertionEffect facebook/react#21913. However, that primarily exists to unblock a few stylesheet libraries from migrating to 18. It's not a Hook you'd want to make a course about because it's not broadly useful. Quite a few things added to React 18 might be like this: only useful to unblock a part of the ecosystem.
  • Concurrent Features
    • 🔴 Some APIs, like SuspenseList, are not documented even in the WG yet. They're not finalized.
    • ✅ New feature: startTransition #41 and useTransition are very likely to keep API (and most of the behavior) as is.
      • 🔴 However, we haven't documented What is the relationship between Suspense and startTransition #85 at all yet. This is a major issue because we expect that in the long run, data re-fetching and router navigations will be the primary use cases for startTransition, while the case we've described today (long re-renders due to expensive work) is actually just a "nice to have". So it's kind of backwards to how we actually expect it to be used. The reason we explained the "long re-renders" case first is because it doesn't force us to explain Suspense (to explain which, we need to explain the data fetching strategy which is still partially in research — see at the bottom).
      • 🟡 There is also an awkward relationship with useDeferredValue. Conceptually, useDeferredValue (not documented yet) is a simpler API. Some of the startTransition examples we've written so far would be easier to write with useDeferredValue. So by the time we document it, we might have to tweak how we explain startTransition. We've delayed documenting useDeferredValue because we didn't want to introduce two very similar concepts at the same time. But we'll need to resolve this by the time we write the actual docs.
  • Suspense
    • ✅ Behavioral changes to Suspense in React 18 #7 and Changes to Suspense effects semantics #31 are likely to stay. However, it's such a deep technical detail and subtle behavior change that focusing attention on it in a course may seem more confusing than skipping it. It's like if you made a course on a React bugfix when people aren't aware the bug existed in the first place.
    • ✅ What is the relationship between Suspense and startTransition #85 is not documented/answered yet, but we feel fairly confident about how this works. In fact, it's one of the really nice things about the design and we hope to find some time to write about it soon-ish.
    • 🟡 New Suspense SSR Architecture in React 18 #37 will likely be unchanged on a high level. However, some individual pieces are either missing or may be outdated.
      • 🟡 Upgrading to React 18 on the server #22 (and pipeToNodeWritable concretely) may change in the exact list of API or options it exposes.
      • ✅ We feel confident in Selective Hydration.
      • ✅ We feel confident in high-level Suspense SSR architecture.
      • 🔴 Event Replaying is likely to be removed and replaced by a simpler mechanism.
      • 🔴 We don't yet have clarity on how exactly data fetching and server/client data cache transfer will be connected. In other words, even though Streaming SSR is meant to enable "waiting for data on the server", we haven't actually decided on how that will work exactly yet, and whether data fetching requires Server Components.
      • 🔴 There are major questions that we're researching, such as how <title> / <head> tags should work with Streaming SSR. This is work in progress and we don't have answers yet. Some new APIs (or not-so-new like useOpaqueIdentifier) might be added.
    • Suspense for Data Fetching
      • 🔴 Explaining it as "throwing Promises" is very misleading because it misses important (semi-undocumented and/or not fully researched) details about the mechanism of how Suspense caches are supposed to work. If you just throw Promises and expect it to work similar to async/await, you're going to have a bad time. We strongly recommend against creating any content about that.
      • 🔴 Built-in Suspense Cache #25 is an essential piece for making Suspense for Data Fetching usable, but the APIs described there are very raw and in research phase. You likely won't see them in the 18.0 release but at some point after. For more details, see Is Suspense for Data Fetching going to be in v18? #49 and What changes are planned for Suspense in 18? #47 (comment).
      • 🟡 If you want to show a sense of how data fetching will likely look like from the user perspective, react-fetch as shown in react-fetch compatibility with 18-alpha releases #80 is very likely to be a representative demo. However, note that it won't work in pure 18 (needs experimental release) yet. Also note that such demos will be very limited because invalidation ("refresh" the data) requires Built-in Suspense Cache #25, which is in research.
  • Tooling
    • 🟡 Introducing a new React profiler #76 is available but might have UI changes (could be significant) before the release.
• Server Components
  • 🔴 While we’re busy with React 18, Server Components is on hold. This means that it’s still in very early research phase.

I hope this gives a sense of where different things are. As you see it's a bit tricky to create content around because "finished" pieces are surrounded by pieces that are in progress or pieces that don't have the right framing yet.

[Andarist]

There will be more work in this area, like [Experimental] Add useInsertionEffect facebook/react#21913. However, that primarily exists to unblock a few stylesheet libraries from migrating to 18. It's not a Hook you'd want to make a course about because it's not broadly useful. Quite a few things added to React 18 might be like this: only useful to unblock a part of the ecosystem.

Oh, wow! This is the very first time I've seen this - it wasn't yet raised in the working group, right? Is there any chance that you could write more context behind this design and how likely is this API to be the final one? Any alternatives that you have considered? What could be other use cases for this beyond CSS-in-JS libraries? What's the story for SSR with this?

[gaearon]

Yeah, we’re planning to write about it in the next few weeks. It’s the “short term solution” mentioned in #83.

[chantastic]

@gaearon thank you. Thank you for your care and attention to detail. This post is detailed and rich with information.

It provides a lot of clarity for us list types.
And it gives great insight into what might and might not be "announced" at the upcoming React Conf.

the documentation rewrite has no relation or coupling to the React 18 release

This makes a lot of sense. And is very good to know.

if you try to infer the vision from individual pieces, it might contradict the vision that we will be sharing.

This is a very important point.
To rephrase as a metaphor. We shouldn't try to "connect the dots" here on our own.
Prematurely adding narrative (and assuming intent) will be misleading. But talking about the atomic changes, as they are, is less destructive.

---

The rest is very beautifully documented and referenced. Thank you for taking the time and care to create this.

[chantastic]

Hey Dan,

In preparation for react.holiday and some end of the year egghead material, I've started to boil the ✅ sections into imperative titles. These are what I have so far. I'm curious if this all feels in-bounds (not to speculative).

Theme: Migrate a Client-Side Application to React 18 (prerelease)

Overview

• Meet the Gradual Adoption Strategy of React 18 (prerelease)
• Update React Dependencies with the @next Version Tag
  • https://reactjs.org/docs/release-channels.html
  • https://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html#how-to-try-react-18-alpha-today

New Root API

• Replace Legacy Root API (render) with New Root API (createRoot)
• Use React 18's New Root API Alongside the Legacy Root API
  • Illustration of using both root APIs on the same page
• Replace Legacy Root API's Callback with Ref Callback
• Conditionally Render with Legacy Root API or New Root API
  • seen in demos (const REACT_18 = true as a stand-in for environment)

Automatic Batching of State Updates

• Opt-in to Automatic Batching with createRoot
• Remove unstable_batchedUpdates Calls
• Opt-out of Automatic Batching with ReactDOM.flushSync
• Fix setState edge-case with ReactDOM.flushSync

WIP

…

Continuation

• Stay up-to-date on React 18 progress with the React Working Group on GitHub