This site runs best with JavaScript enabled.

How to Enable React Concurrent Mode

Software Engineer, React Training, Testing JavaScript Training

Photo by Marc Schulte


Concurrent Mode is an enormous improvement for user experience and developer experience. Here's how you enable it.

React's new Concurrent Mode has just been published in the experimental release channel. It's the result of years of research and that shows. If you'd like to learn more about why it's so cool, definitely watch Dan Abramov's talk at JSIceland. And people have started playing around with it and seeing some nice perf wins out of the box.

All that said, please remember that this is experimental. The experimental release channel does not honor semver (so code relying on it could break unexpectedly) and there could definitely be bugs. But early experimentation has been promising for many and I suggest that you try it out in your own app.

Step 1

Get it installed.

First, to enable Concurrent Mode, you'll need to have a version of React that supports this. At the time of this writing, React and React DOM are at version 16.11.0 which does not support Concurrent Mode. So we'll need to install the experimental version:

1npm install react@experimental react-dom@experimental
2# or: yarn add react@experimental react-dom@experimental

Step 2

Make sure your app works without changing anything else.

Run your app, run your build, run your tests/type checking. If there are new errors in the console that weren't there before, then those might be bugs in React and you should try to make a minimal reproduction (preferably in a codesandbox) and open a new issue on the React repo.

Often we skip this step, but I think it's important to make sure that if there are problems you know which step these problems started at! Good advice in general I'd say 😉

Step 3

Enable Concurrent Mode.

In the entry file of your project, you probably have something that looks like this:

1import React from 'react'
2import ReactDOM from 'react-dom'
3import App from './app'
4
5const rootEl = document.getElementById('root')
6ReactDOM.render(<App />, rootEl)

To enable Concurrent Mode, you'll use a new createRoot API:

1import React from 'react'
2import ReactDOM from 'react-dom'
3import App from './app'
4
5const rootEl = document.getElementById('root')
6// ReactDOM.render(<App />, rootEl)
7const root = ReactDOM.createRoot(rootEl)
8root.render(<App />)

That's it.

Step 4

Make sure your app works without changing anything else.

Run your app, run your build, run your tests/type checking. If there are new errors in the console that weren't there before, then those might be bugs in React and you should try to make a minimal reproduction (preferably in a codesandbox) and open a new issue on the React repo.

If that looks familiar, it's because I copy/pasted it from step 2 😂

In this case however, if things are broken or you have new errors in the console. It may be because there's code in your app that's using features not supported in Concurrent Mode (like String Refs, Legacy Context, or findDOMNode).

Also please note that all the lifecycle methods that have the unsafe_ prefix are now actually unsafe and you will experience bugs using those.

Step 5

Try out Concurrent Mode. There are two primary things that Concurrent Mode enables for us:

  1. Time Slicing
  2. Suspense for everything asynchronous

If you have some user interaction in your app that you know is slow, try that out and if it's less janky, that's time slicing at work (watch Dan's talk linked above for more about this).

You can try refactoring one of your asynchronous interactions to suspense, or just try adding this to somewhere in your app:

1const TRANSITION_CONFIG = {
2 timeoutMs: 3000, // 🐨 Play with this number a bit...
3}
4function SuspenseDemo() {
5 const [greetingResource, setGreetingResource] = React.useState(null)
6 const [startTransition, isPending] = React.useTransition(TRANSITION_CONFIG)
7
8 function handleSubmit(event) {
9 event.preventDefault()
10 const name = event.target.elements.nameInput.value
11 startTransition(() => {
12 setGreetingResource(createGreetingResource(name))
13 })
14 }
15
16 return (
17 <div>
18 <strong>Suspense Demo</strong>
19 <form onSubmit={handleSubmit}>
20 <label htmlFor="nameInput">Name</label>
21 <input id="nameInput" />
22 <button type="submit">Submit</button>
23 </form>
24 <ErrorBoundary>
25 <React.Suspense fallback={<p>loading greeting</p>}>
26 <Greeting greetingResource={greetingResource} isPending={isPending} />
27 </React.Suspense>
28 </ErrorBoundary>
29 </div>
30 )
31}
32
33function Greeting({greetingResource, isPending}) {
34 return (
35 <p style={{opacity: isPending ? 0.4 : 1}}>
36 {greetingResource ? greetingResource.read() : 'Please submit a name'}
37 </p>
38 )
39}
40
41// 🐨 make this function do something else. Like an HTTP request or something
42function getGreeting(name) {
43 return new Promise((resolve, reject) => {
44 setTimeout(() => {
45 resolve(`Hello ${name}!`)
46 // 🐨 try rejecting instead... (make sure to comment out the resolve call)
47 // reject(new Error(`Oh no. Could not load greeting for ${name}`))
48 }, 1500) // 🐨 play with this number a bit
49 })
50}
51
52// 🚨 This should NOT be copy/pasted for production code and is only here
53// for experimentation purposes. The API for suspense (currently throwing a
54// promise) is likely to change before suspense is officially released.
55function createGreetingResource(name) {
56 let status = 'pending'
57 let result
58 let suspender = getGreeting(name).then(
59 greeting => {
60 status = 'success'
61 result = greeting
62 },
63 error => {
64 status = 'error'
65 result = error
66 },
67 )
68 return {
69 read() {
70 if (status === 'pending') throw suspender
71 if (status === 'error') throw result
72 if (status === 'success') return result
73 },
74 }
75}
76
77class ErrorBoundary extends React.Component {
78 state = {error: null}
79 static getDerivedStateFromError(error) {
80 return {error}
81 }
82 componentDidCatch() {
83 // log the error to the server
84 }
85 tryAgain = () => this.setState({error: null})
86 render() {
87 return this.state.error ? (
88 <div>
89 There was an error. <button onClick={this.tryAgain}>try again</button>
90 <pre style={{whiteSpace: 'normal'}}>{this.state.error.message}</pre>
91 </div>
92 ) : (
93 this.props.children
94 )
95 }
96}

Play with this on codesandbox instead

One thing that I've found is that the suspense APIs are pretty low-level, so there's a lot of code needed to make it work well. But the cool thing is that these are atomic features which work really well within an abstraction and can be easily shared. So once you've got that abstraction, you're golden. It's awesome.

Step 6

Undo all your changes.

Reinstall the last stable version you had installed before, and restore the old ReactDOM.render you had before. Concurrent Mode is experimental, and even if it doesn't look like there are problems, shipping experimental software as foundational as React is ill-advised. The React docs even suggest that depending on the size of your app and the third party libraries you're using, you may never be able to ship Concurrent Mode (Facebook currently has no plans to enable Concurrent Mode on the old Facebook.com).

Remember also that we as a community are just starting to play around with this stuff, so there are still a lot of unknowns around trade-offs for different approaches. It's an exciting time. But if you value stability, then maybe pretend Concurrent Mode and suspense don't exist for a little while.

Step 7

Enable Strict Mode.

Apps that don't pass Strict Mode are unlikely to work well in Concurrent Mode. So if you want to work toward enabling Concurrent Mode on your app, then enable Strict Mode. One nice thing about Strict Mode is (unlike Concurrent Mode) it's incrementally adoptable. So you can apply Strict Mode to only the part of your codebase that you know is compliant and then iterate to full support over time.

Read more about this on my blog: How to Enable React Strict Mode.

Conclusion

I'm really looking forward to the stable release of Concurrent Mode and Suspense for data fetching. It's going to be even cooler when frameworks and libraries take advantage of these new features. As awesome as React Hooks were for the React ecosystem, I think that Concurrent Mode will be more impactful for both developer experience and the end user.

Enjoy experimenting!

Discuss on TwitterEdit post on GitHub

Share article
loading relevant upcoming workshops...
Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.