Moving createRoot/hydrateRoot to react-dom/client

[rickhanlonii]

Overview

For the next React 18 RC (RC 1) we're moving both createRoot and hydrateRoot to react-dom/client:

import * as ReactDOMClient from 'react-dom/client';

ReactDOMClient.createRoot(/*...*/);

ReactDOMClient.hydrateRoot(/*...*/);

Using these APIs from the top level will now warn.

Motivation

There are two reasons for this change.

First, it allows components to use the isomorphic APIs such as flushSync without pulling in the client-specific entry. This means that if you server render a component that only uses flushSync on the client, the server doesn't need to pull in the client-specific code for createRoot or hydrateRoot.

Second, it creates parity with react-dom/server:

Before:

// For client createRoot or hydrateRoot
import * as ReactDOM from 'react-dom';

// For server rendering
import * as ReactDOM from 'react-dom/server';

After:

// For client createRoot or hydrateRoot
import * as ReactDOMClient from 'react-dom/client';

// For renderToPipeableStream or renderToReadableStream
import * as ReactDOMServer from 'react-dom/server';

Warnings

When you first upgrade to RC 1 from previous React 18 pre-release versions, you'll see a warning when using the top level functions.

For createRoot:

You are importing createRoot from "react-dom" which is not supported. You should instead import it from "react-dom/client.

For hydrateRoot:

You are importing hydrateRoot from "react-dom" which is not supported. You should instead import it from "react-dom/client".

For more information see react/react#23385

[Andarist]

If flushSync is isomorphic… shouldnt it just be exported by React itself? Are there any renderers that dont support this?

I’ve also noticed that you are using inconsistent import styles and I believe that it should be fixed - either stick to a default import or to a namespace import

[rickhanlonii]

Good question. flushSync is specific to ReactDOM. Other renderers will have their own API for similar capabilities. For example, React Native may have a different JS API or a native API because the threading model is different and there's more control of the runtime.

[Andarist]

@eps1lon did u have a chance to rethink the impact on the libraries that you maintain (such as RTL)?

Is React team still OK with making it impossible/hard for certain libraries to depend on ^16.8 || 17.x || 18.x? This might create some churn/problems in the ecosystem for maintainers as they would have to bump their major versions just to avoid noisy warnings for their consumers when their libs are going to be used with React 18

[sebmarkbage]

Btw, be careful not do to any LiveAnnouncer things inside of render. We did that for announcing errors at FB and the sync renders starves out the async renders of the other tree.

[sebmarkbage]

useDrag needs to be able to synchronously render a component during the onDragStart DOM event to use as the preview image while dragging. We don't really want to render the preview image for all draggable elements ahead of time.

You could maybe flushSync(() => setState(...)) and render the Portal synchronously?

LiveAnnouncer is more of an API thing. It's just a "global" function you call from somewhere in your code, not a thing you render in a specific component. We manage rendering the required DOM nodes.

It'd be nicer to have some kind output where you can choose where all those should go. Like a Component that registers itself to receive events that gets queued to be rendered by that component. Even if those end up as Portals. That way you can also have them automatically hide with the shell that they're attached to and work with Offscreen features.

[devongovett]

You could maybe flushSync(() => setState(...)) and render the Portal synchronously?

Yeah, though as a hooks-only library, we'd have to make consumers render an additional component somewhere in their app for this to work.

It'd be nicer to have some kind output where you can choose where all those should go.

Yeah possibly. But we'd need to verify that you only ever render a single one of these anyway, or messages will be duplicated. These are not visible, they are just used for screen reader announcement, so it doesn't really matter too much where they end up in the DOM. The document body is usually a good place because it avoids them being accidentally placed in an aria-hidden subtree.

[sebmarkbage]

Multiple roots don't have any particular defined order with regard to which one wins etc when it comes to scheduling since it's not encoded. It also doesn't encode things like "offscreen" mode if its parent hides or get virtualized. What happens if something suspends (the assumption is that we'll have automatically suspending things like auto-lazy, so anything could suspend), what part of the UI is it a necessary part of? And ofc, Context.

The idea is that any component author throughout the ecosystem should be able to rely on these rather than having to keep in mind whether they're in a special context or not.

The other aspect is that ideally you should be able to build SPAs where basically the whole shell is swappable client side or has bottom/top bars that conceptually outside the app. Therefore even global UIs should ideally have some kind of context for which shell they're conceptually stacked into. We also have plans for a "backgrounded" mode where something can keep living inside the tree while the outside is more or less frozen or deprioritized. Portals can then stick out of the backgrounded mode.

That's why Portals are recommended as a way to preserve some sense of the conceptual context where something belongs so all those things can happen automatically.

In the ToastManager case, that seems like a case where you actually don't want to carry over the context of where you're executing. E.g. unlike a tooltip you don't need to hide the toast when the parent hides. That's probably a good candidate for just having a component that lets you place the rendering of the Toasts somewhere in the tree. Like having a singleton component register itself with the ToastManager and listen to things it should render. No Portals. Maybe that could be made a requirement for 18, and otherwise it still works but you get the warning.

The LiveAnnouncer is interesting because it doesn't accept arbitrary React children so there's no confusion other than internals. Tbh, in this case I'd just not use React at all and just insert manual DOM nodes. It's just simulating a text-based API anyway.

The useDrag example is interesting since it's an example where you can't have any typical expectations of what you can do in a React component because it's synchronous, frozen and non-interactive. I think you probably can have the expectation that you inherit Contexts (e.g. theme or other things) though when rendering an icon or whatever. It would be nice if it was a Portal for that reason.

In this case it would be nice if you could have a Portal in a Hook. However, that's usually not necessarily the best, because placing it in the tree gives meaning to where it is in the tree for event bubbling, and where it suspends. E.g. it gives you an option to wrap it in a Suspense boundary and give it semantics with SuspenseList.

In this special case, since it has no semantics related to the tree other than the Context, it would be nice if we had a usePortal API.

@devongovett Note that if the user uses some kind of framework that registers itself in an useEffect or something inside the Preview component. An easy mistake to make if you use pretty much any framework. It'll currently leak because you don't unmount the root. The new root API will likely start warning for that case. If you have multiple roots and the root gets dropped without ever unmounting (using weakrefs). I'd probably make sense to unmount it before removeChild is called.

[devongovett]

Finally had time to work on this.

• For LiveAnnouncer, I reimplemented it using vanilla DOM. adobe/react-spectrum@b3a27a5
• For useDrag, we had to make a breaking API change, but I think it's worth it because you get other benefits like context and style inheritance working as expected, and can control where it renders in the React tree. Bit of an interesting API to "connect" the DragPreview with the useDrag hook via a ref, but seems to work. We'll find out whether people find this API confusing or not. 😄 adobe/react-spectrum@7215206

Thanks again for your help/suggestions.