From 6ebb6d8005b053f7b29d47a7a59f4c715f55e990 Mon Sep 17 00:00:00 2001 From: Raghav Goyal Date: Sat, 9 May 2020 20:28:09 +0530 Subject: [PATCH 1/2] Rename createRoot & createBlockingRoot to unstable_createRoot & unstable_createBlockingRoot --- content/docs/concurrent-mode-adoption.md | 10 +++++----- content/docs/concurrent-mode-patterns.md | 4 ++-- content/docs/concurrent-mode-reference.md | 12 ++++++------ 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/content/docs/concurrent-mode-adoption.md b/content/docs/concurrent-mode-adoption.md index 347a7a1106b..e9a1d8b4478 100644 --- a/content/docs/concurrent-mode-adoption.md +++ b/content/docs/concurrent-mode-adoption.md @@ -71,14 +71,14 @@ import ReactDOM from 'react-dom'; // // You can opt into Concurrent Mode by writing: -ReactDOM.createRoot( +ReactDOM.unstable_createRoot( document.getElementById('root') ).render(); ``` >Note: > ->Concurrent Mode APIs such as `createRoot` only exist in the experimental builds of React. +>Concurrent Mode APIs such as `unstable_createRoot` only exist in the experimental builds of React. In Concurrent Mode, the lifecycle methods [previously marked](/blog/2018/03/27/update-on-async-rendering.html) as "unsafe" actually *are* unsafe, and lead to bugs even more than in today's React. We don't recommend trying Concurrent Mode until your app is [Strict Mode](/docs/strict-mode.html)-compatible. @@ -90,13 +90,13 @@ In our experience, code that uses idiomatic React patterns and doesn't rely on e ### Migration Step: Blocking Mode {#migration-step-blocking-mode} -For older codebases, Concurrent Mode might be a step too far. This is why we also provide a new "Blocking Mode" in the experimental React builds. You can try it by substituting `createRoot` with `createBlockingRoot`. It only offers a *small subset* of the Concurrent Mode features, but it is closer to how React works today and can serve as a migration step. +For older codebases, Concurrent Mode might be a step too far. This is why we also provide a new "Blocking Mode" in the experimental React builds. You can try it by substituting `unstable_createRoot` with `unstable_createBlockingRoot`. It only offers a *small subset* of the Concurrent Mode features, but it is closer to how React works today and can serve as a migration step. To recap: * **Legacy Mode:** `ReactDOM.render(, rootNode)`. This is what React apps use today. There are no plans to remove the legacy mode in the observable future — but it won't be able to support these new features. -* **Blocking Mode:** `ReactDOM.createBlockingRoot(rootNode).render()`. It is currently experimental. It is intended as a first migration step for apps that want to get a subset of Concurrent Mode features. -* **Concurrent Mode:** `ReactDOM.createRoot(rootNode).render()`. It is currently experimental. In the future, after it stabilizes, we intend to make it the default React mode. This mode enables *all* the new features. +* **Blocking Mode:** `ReactDOM.unstable_createBlockingRoot(rootNode).render()`. It is currently experimental. It is intended as a first migration step for apps that want to get a subset of Concurrent Mode features. +* **Concurrent Mode:** `ReactDOM.unstable_createRoot(rootNode).render()`. It is currently experimental. In the future, after it stabilizes, we intend to make it the default React mode. This mode enables *all* the new features. ### Why So Many Modes? {#why-so-many-modes} diff --git a/content/docs/concurrent-mode-patterns.md b/content/docs/concurrent-mode-patterns.md index 3f863e49775..4306129a821 100644 --- a/content/docs/concurrent-mode-patterns.md +++ b/content/docs/concurrent-mode-patterns.md @@ -57,12 +57,12 @@ React offers a new built-in `useTransition()` Hook to help with this. We can use it in three steps. -First, we'll make sure that we're actually using Concurrent Mode. We'll talk more about [adopting Concurrent Mode](/docs/concurrent-mode-adoption.html) later, but for now it's sufficient to know that we need to use `ReactDOM.createRoot()` rather than `ReactDOM.render()` for this feature to work: +First, we'll make sure that we're actually using Concurrent Mode. We'll talk more about [adopting Concurrent Mode](/docs/concurrent-mode-adoption.html) later, but for now it's sufficient to know that we need to use `ReactDOM.unstable_createRoot()` rather than `ReactDOM.render()` for this feature to work: ```js const rootElement = document.getElementById("root"); // Opt into Concurrent Mode -ReactDOM.createRoot(rootElement).render(); +ReactDOM.unstable_createRoot(rootElement).render(); ``` Next, we'll add an import for the `useTransition` Hook from React: diff --git a/content/docs/concurrent-mode-reference.md b/content/docs/concurrent-mode-reference.md index 663af1b3bf0..9668e99b453 100644 --- a/content/docs/concurrent-mode-reference.md +++ b/content/docs/concurrent-mode-reference.md @@ -27,8 +27,8 @@ This page is an API reference for the React [Concurrent Mode](/docs/concurrent-m **Note: This is a Community Preview and not the final stable version. There will likely be future changes to these APIs. Use at your own risk!** - [Enabling Concurrent Mode](#concurrent-mode) - - [`createRoot`](#createroot) - - [`createBlockingRoot`](#createblockingroot) + - [`unstable_createRoot`](#unstable_createroot) + - [`unstable_createBlockingRoot`](#unstable_createBlockingRoot) - [Suspense](#suspense) - [`Suspense`](#suspensecomponent) - [`SuspenseList`](#suspenselist) @@ -37,20 +37,20 @@ This page is an API reference for the React [Concurrent Mode](/docs/concurrent-m ## Enabling Concurrent Mode {#concurrent-mode} -### `createRoot` {#createroot} +### `unstable_createRoot` {#unstable_createRoot} ```js -ReactDOM.createRoot(rootNode).render(); +ReactDOM.unstable_createRoot(rootNode).render(); ``` Replaces `ReactDOM.render(, rootNode)` and enables Concurrent Mode. For more information on Concurrent Mode, check out the [Concurrent Mode documentation.](/docs/concurrent-mode-intro.html) -### `createBlockingRoot` {#createblockingroot} +### `unstable_createBlockingRoot` {#unstable_createBlockingRoot} ```js -ReactDOM.createBlockingRoot(rootNode).render() +ReactDOM.unstable_createBlockingRoot(rootNode).render() ``` Replaces `ReactDOM.render(, rootNode)` and enables [Blocking Mode](/docs/concurrent-mode-adoption.html#migration-step-blocking-mode). From f391b59262965386974ec03121627d6a9820dc61 Mon Sep 17 00:00:00 2001 From: Raghav Goyal Date: Sun, 10 May 2020 08:39:00 +0530 Subject: [PATCH 2/2] fix 1.0 --- content/docs/concurrent-mode-patterns.md | 24 +++++++++---------- content/docs/concurrent-mode-reference.md | 28 +++++++++++++++-------- 2 files changed, 30 insertions(+), 22 deletions(-) diff --git a/content/docs/concurrent-mode-patterns.md b/content/docs/concurrent-mode-patterns.md index 4306129a821..490eee5383a 100644 --- a/content/docs/concurrent-mode-patterns.md +++ b/content/docs/concurrent-mode-patterns.md @@ -68,7 +68,7 @@ ReactDOM.unstable_createRoot(rootElement).render(); Next, we'll add an import for the `useTransition` Hook from React: ```js -import React, { useState, useTransition, Suspense } from "react"; +import React, { useState, unstable_useTransition, Suspense } from "react"; ``` Finally, we'll use it inside the `App` component: @@ -76,7 +76,7 @@ Finally, we'll use it inside the `App` component: ```js{3-5} function App() { const [resource, setResource] = useState(initialResource); - const [startTransition, isPending] = useTransition({ + const [startTransition, isPending] = unstable_useTransition({ timeoutMs: 3000 }); // ... @@ -130,7 +130,7 @@ There's still something that feels broken about [our last example](https://codes Our `useTransition()` call returns two values: `startTransition` and `isPending`. ```js - const [startTransition, isPending] = useTransition({ timeoutMs: 3000 }); + const [startTransition, isPending] = unstable_useTransition({ timeoutMs: 3000 }); ``` We've already used `startTransition` to wrap the state update. Now we're going to use `isPending` too. React gives this boolean to us so we can tell whether **we're currently waiting for this transition to finish**. We'll use it to indicate that something is happening: @@ -166,7 +166,7 @@ Let's take another look at all the changes we've made since the [original exampl ```js{3-5,9,11,14,19} function App() { const [resource, setResource] = useState(initialResource); - const [startTransition, isPending] = useTransition({ + const [startTransition, isPending] = unstable_useTransition({ timeoutMs: 3000 }); return ( @@ -193,7 +193,7 @@ function App() { It took us only seven lines of code to add this transition: -* We've imported the `useTransition` Hook and used it the component that updates the state. +* We've imported the `unstable_useTransition` Hook and used it the component that updates the state. * We've passed `{timeoutMs: 3000}` to stay on the previous screen for at most 3 seconds. * We've wrapped our state update into `startTransition` to tell React it's okay to delay it. * We're using `isPending` to communicate the state transition progress to the user and to disable the button. @@ -258,7 +258,7 @@ However, the experience feels really jarring. We were browsing a page, but it go ```js{2-5,9-11,21} function ProfilePage() { - const [startTransition, isPending] = useTransition({ + const [startTransition, isPending] = unstable_useTransition({ // Wait 10 seconds before fallback timeoutMs: 10000 }); @@ -299,7 +299,7 @@ This can lead to a lot of repetitive code across components. This is why **we ge ```js{7-9,20,24} function Button({ children, onClick }) { - const [startTransition, isPending] = useTransition({ + const [startTransition, isPending] = unstable_useTransition({ timeoutMs: 10000 }); @@ -678,7 +678,7 @@ As we mentioned earlier, if some state update causes a component to suspend, tha function App() { const [query, setQuery] = useState(initialQuery); const [resource, setResource] = useState(initialResource); - const [startTransition, isPending] = useTransition({ + const [startTransition, isPending] = unstable_useTransition({ timeoutMs: 5000 }); @@ -743,9 +743,9 @@ This makes sense in the vast majority of situations. Inconsistent UI is confusin However, sometimes it might be helpful to intentionally introduce an inconsistency. We could do it manually by "splitting" the state like above, but React also offers a built-in Hook for this: ```js -import { useDeferredValue } from 'react'; +import { unstable_useDeferredValue } from 'react'; -const deferredValue = useDeferredValue(value, { +const deferredValue = unstable_useDeferredValue(value, { timeoutMs: 5000 }); ``` @@ -758,7 +758,7 @@ If we're willing to sacrifice consistency, we could **pass potentially stale dat ```js{2-4,10,11,21} function ProfilePage({ resource }) { - const deferredResource = useDeferredValue(resource, { + const deferredResource = unstable_useDeferredValue(resource, { timeoutMs: 1000 }); return ( @@ -826,7 +826,7 @@ We can see how typing in the input causes stutter. Now let's add `useDeferredVal ```js{3-5,18} function App() { const [text, setText] = useState("hello"); - const deferredText = useDeferredValue(text, { + const deferredText = unstable_useDeferredValue(text, { timeoutMs: 5000 }); diff --git a/content/docs/concurrent-mode-reference.md b/content/docs/concurrent-mode-reference.md index 9668e99b453..f3a57cf5707 100644 --- a/content/docs/concurrent-mode-reference.md +++ b/content/docs/concurrent-mode-reference.md @@ -27,17 +27,25 @@ This page is an API reference for the React [Concurrent Mode](/docs/concurrent-m **Note: This is a Community Preview and not the final stable version. There will likely be future changes to these APIs. Use at your own risk!** - [Enabling Concurrent Mode](#concurrent-mode) - - [`unstable_createRoot`](#unstable_createroot) - - [`unstable_createBlockingRoot`](#unstable_createBlockingRoot) + - [`createRoot`](#createroot) + - [`createBlockingRoot`](#createBlockingRoot) - [Suspense](#suspense) - [`Suspense`](#suspensecomponent) - [`SuspenseList`](#suspenselist) - [`useTransition`](#usetransition) - [`useDeferredValue`](#usedeferredvalue) +**Note: All the Apis from concurrent mode are exported with unstable_ prefix as they are still experimental and may change drastically in near future.** + - createRoot as unstable_createRoot + - createBlockingRoot as unstable_createBlockingRoot' + - useTransition as unstable_useTransition + - useDeferredValue as unstable_useDeferredValue + - SuspenseList as unstable_SuspenseList + + ## Enabling Concurrent Mode {#concurrent-mode} -### `unstable_createRoot` {#unstable_createRoot} +### `createRoot` {#createRoot} ```js ReactDOM.unstable_createRoot(rootNode).render(); @@ -47,7 +55,7 @@ Replaces `ReactDOM.render(, rootNode)` and enables Concurrent Mode. For more information on Concurrent Mode, check out the [Concurrent Mode documentation.](/docs/concurrent-mode-intro.html) -### `unstable_createBlockingRoot` {#unstable_createBlockingRoot} +### `createBlockingRoot` {#createBlockingRoot} ```js ReactDOM.unstable_createBlockingRoot(rootNode).render() @@ -81,7 +89,7 @@ In this example, `ProfileDetails` is waiting for an asynchronous API call to fet ### `` {#suspenselist} ```js - + @@ -92,7 +100,7 @@ In this example, `ProfileDetails` is waiting for an asynchronous API call to fet ... - + ``` `SuspenseList` helps coordinate many components that can suspend by orchestrating the order in which these components are revealed to the user. @@ -114,7 +122,7 @@ Note that `SuspenseList` only operates on the closest `Suspense` and `SuspenseLi ```js const SUSPENSE_CONFIG = { timeoutMs: 2000 }; -const [startTransition, isPending] = useTransition(SUSPENSE_CONFIG); +const [startTransition, isPending] = unstable_useTransition(SUSPENSE_CONFIG); ``` `useTransition` allows components to avoid undesirable loading states by waiting for content to load before **transitioning to the next screen**. It also allows components to defer slower, data fetching updates until subsequent renders so that more crucial updates can be rendered immediately. @@ -130,7 +138,7 @@ const SUSPENSE_CONFIG = { timeoutMs: 2000 }; function App() { const [resource, setResource] = useState(initialResource); - const [startTransition, isPending] = useTransition(SUSPENSE_CONFIG); + const [startTransition, isPending] = unstable_useTransition(SUSPENSE_CONFIG); return ( <>