As we shared in the release post, React 18 introduces features powered by our new concurrent renderer, with a gradual adoption strategy for existing applications. In this post, we will guide you through the steps for upgrading to React 18.
\nPlease report any issues you encounter while upgrading to React 18.
\nNote for React Native users: React 18 will ship in a future version of React Native. This is because React 18 relies on the New React Native Architecture to benefit from the new capabilities presented in this blogpost. For more information, see the React Conf keynote here.
\nTo install the latest version of React:
\nnpm install react react-domOr if you’re using yarn:
\nyarn add react react-domWhen you first install React 18, you will see a warning in the console:
\n\n\nReactDOM.render is no longer supported in React 18. Use createRoot instead. Until you switch to the new API, your app will behave as if it’s running React 17. Learn more: https://reactjs.org/link/switch-to-createroot
\n
React 18 introduces a new root API which provides better ergonomics for managing roots. The new root API also enables the new concurrent renderer, which allows you to opt-into concurrent features.
\n// Before\nimport { render } from 'react-dom';\nconst container = document.getElementById('app');\nrender(<App tab=\"home\" />, container);\n\n// After\nimport { createRoot } from 'react-dom/client';\nconst container = document.getElementById('app');\nconst root = createRoot(container); // createRoot(container!) if you use TypeScript\nroot.render(<App tab=\"home\" />);We’ve also changed unmountComponentAtNode to root.unmount:
// Before\nunmountComponentAtNode(container);\n\n// After\nroot.unmount();We’ve also removed the callback from render, since it usually does not have the expected result when using Suspense:
\n// Before\nconst container = document.getElementById('app');\nrender(<App tab=\"home\" />, container, () => {\n console.log('rendered');\n});\n\n// After\nfunction AppWithCallbackAfterRender() {\n useEffect(() => {\n console.log('rendered');\n });\n\n return <App tab=\"home\" />\n}\n\nconst container = document.getElementById('app');\nconst root = createRoot(container);\nroot.render(<AppWithCallbackAfterRender />);\n\nNote:
\nThere is no one-to-one replacement for the old render callback API — it depends on your use case. See the working group post for Replacing render with createRoot for more information.
\n
Finally, if your app uses server-side rendering with hydration, upgrade hydrate to hydrateRoot:
// Before\nimport { hydrate } from 'react-dom';\nconst container = document.getElementById('app');\nhydrate(<App tab=\"home\" />, container);\n\n// After\nimport { hydrateRoot } from 'react-dom/client';\nconst container = document.getElementById('app');\nconst root = hydrateRoot(container, <App tab=\"home\" />);\n// Unlike with createRoot, you don't need a separate root.render() call here.For more information, see the working group discussion here.
\n\n\nNote
\nIf your app doesn’t work after upgrading, check whether it’s wrapped in
\n<StrictMode>. Strict Mode has gotten stricter in React 18, and not all your components may be resilient to the new checks it adds in development mode. If removing Strict Mode fixes your app, you can remove it during the upgrade, and then add it back (either at the top or for a part of the tree) after you fix the issues that it’s pointing out.
In this release, we’re revamping our react-dom/server APIs to fully support Suspense on the server and Streaming SSR. As part of these changes, we’re deprecating the old Node streaming API, which does not support incremental Suspense streaming on the server.
Using this API will now warn:
\nrenderToNodeStream: Deprecated ⛔️️Instead, for streaming in Node environments, use:
\nrenderToPipeableStream: New ✨We’re also introducing a new API to support streaming SSR with Suspense for modern edge runtime environments, such as Deno and Cloudflare workers:
\nrenderToReadableStream: New ✨The following APIs will continue working, but with limited support for Suspense:
\nrenderToString: Limited ⚠️renderToStaticMarkup: Limited ⚠️Finally, this API will continue to work for rendering e-mails:
\nrenderToStaticNodeStreamFor more information on the changes to server rendering APIs, see the working group post on Upgrading to React 18 on the server, a deep dive on the new Suspense SSR Architecture, and Shaundai Person’s talk on Streaming Server Rendering with Suspense at React Conf 2021.
\nIf your project uses TypeScript, you will need to update your @types/react and @types/react-dom dependencies to the latest versions. The new types are safer and catch issues that used to be ignored by the type checker. The most notable change is that the children prop now needs to be listed explicitly when defining props, for example:
interface MyButtonProps {\n color: string;\n children?: React.ReactNode;}See the React 18 typings pull request for a full list of type-only changes. It links to example fixes in library types so you can see how to adjust your code. You can use the automated migration script to help port your application code to the new and safer typings faster.
\nIf you find a bug in the typings, please file an issue in the DefinitelyTyped repo.
\nReact 18 adds out-of-the-box performance improvements by doing more batching by default. Batching is when React groups multiple state updates into a single re-render for better performance. Before React 18, we only batched updates inside React event handlers. Updates inside of promises, setTimeout, native event handlers, or any other event were not batched in React by default:
\n// Before React 18 only React events were batched\n\nfunction handleClick() {\n setCount(c => c + 1);\n setFlag(f => !f);\n // React will only re-render once at the end (that's batching!)\n}\n\nsetTimeout(() => {\n setCount(c => c + 1);\n setFlag(f => !f);\n // React will render twice, once for each state update (no batching)\n}, 1000);Starting in React 18 with createRoot, all updates will be automatically batched, no matter where they originate from. This means that updates inside of timeouts, promises, native event handlers or any other event will batch the same way as updates inside of React events:
// After React 18 updates inside of timeouts, promises,\n// native event handlers or any other event are batched.\n\nfunction handleClick() {\n setCount(c => c + 1);\n setFlag(f => !f);\n // React will only re-render once at the end (that's batching!)\n}\n\nsetTimeout(() => {\n setCount(c => c + 1);\n setFlag(f => !f);\n // React will only re-render once at the end (that's batching!)\n}, 1000);This is a breaking change, but we expect this to result in less work rendering, and therefore better performance in your applications. To opt-out of automatic batching, you can use flushSync:
import { flushSync } from 'react-dom';\n\nfunction handleClick() {\n flushSync(() => {\n setCounter(c => c + 1);\n });\n // React has updated the DOM by now\n flushSync(() => {\n setFlag(f => !f);\n });\n // React has updated the DOM by now\n}For more information, see the Automatic batching deep dive.
\nIn the React 18 Working Group we worked with library maintainers to create new APIs needed to support concurrent rendering for use cases specific to their use case in areas like styles, and external stores. To support React 18, some libraries may need to switch to one of the following APIs:
\nuseSyncExternalStore is a new hook that allows external stores to support concurrent reads by forcing updates to the store to be synchronous. This new API is recommended for any library that integrates with state external to React. For more information, see the useSyncExternalStore overview post and useSyncExternalStore API details.useInsertionEffect is a new hook that allows CSS-in-JS libraries to address performance issues of injecting styles in render. Unless you’ve already built a CSS-in-JS library we don’t expect you to ever use this. This hook will run after the DOM is mutated, but before layout effects read the new layout. This solves an issue that already exists in React 17 and below, but is even more important in React 18 because React yields to the browser during concurrent rendering, giving it a chance to recalculate layout. For more information, see the Library Upgrade Guide for <style>.React 18 also introduces new APIs for concurrent rendering such as startTransition, useDeferredValue and useId, which we share more about in the release post.
In the future, we’d like to add a feature that allows React to add and remove sections of the UI while preserving state. For example, when a user tabs away from a screen and back, React should be able to immediately show the previous screen. To do this, React would unmount and remount trees using the same component state as before.
\nThis feature will give React better performance out-of-the-box, but requires components to be resilient to effects being mounted and destroyed multiple times. Most effects will work without any changes, but some effects assume they are only mounted or destroyed once.
\nTo help surface these issues, React 18 introduces a new development-only check to Strict Mode. This new check will automatically unmount and remount every component, whenever a component mounts for the first time, restoring the previous state on the second mount.
\nBefore this change, React would mount the component and create the effects:
\n* React mounts the component.\n * Layout effects are created.\n * Effect effects are created.With Strict Mode in React 18, React will simulate unmounting and remounting the component in development mode:
\n* React mounts the component.\n * Layout effects are created.\n * Effect effects are created.\n* React simulates unmounting the component.\n * Layout effects are destroyed.\n * Effects are destroyed.\n* React simulates mounting the component with the previous state.\n * Layout effect setup code runs\n * Effect setup code runsFor more information, see the Working Group posts for Adding Reusable State to StrictMode and How to support Reusable State in Effects.
\nWhen you first update your tests to use createRoot, you may see this warning in your test console:
\n\nThe current testing environment is not configured to support act(…)
\n
To fix this, set globalThis.IS_REACT_ACT_ENVIRONMENT to true before running your test:
// In your test setup file\nglobalThis.IS_REACT_ACT_ENVIRONMENT = true;The purpose of the flag is to tell React that it’s running in a unit test-like environment. React will log helpful warnings if you forget to wrap an update with act.
You can also set the flag to false to tell React that act isn’t needed. This can be useful for end-to-end tests that simulate a full browser environment.
Eventually, we expect testing libraries will configure this for you automatically. For example, the next version of React Testing Library has built-in support for React 18 without any additional configuration.
\nMore background on the act testing API and related changes is available in the working group.
In this release, React is dropping support for Internet Explorer, which is going out of support on June 15, 2022. We’re making this change now because new features introduced in React 18 are built using modern browser features such as microtasks which cannot be adequately polyfilled in IE.
\nIf you need to support Internet Explorer we recommend you stay with React 17.
\nreact-dom: ReactDOM.render has been deprecated. Using it will warn and run your app in React 17 mode.react-dom: ReactDOM.hydrate has been deprecated. Using it will warn and run your app in React 17 mode.react-dom: ReactDOM.unmountComponentAtNode has been deprecated.react-dom: ReactDOM.renderSubtreeIntoContainer has been deprecated.react-dom/server: ReactDOMServer.renderToNodeStream has been deprecated.<Suspense> boundary in the tree. This ensures the hydrated tree is consistent and avoids potential privacy and security holes that can be caused by hydration mismatches.Promise, Symbol, and Object.assign. If you support older browsers and devices such as Internet Explorer which do not provide modern browser features natively or have non-compliant implementations, consider including a global polyfill in your bundled application.undefined: React no longer warns if you return undefined from a component. This makes the allowed component return values consistent with values that are allowed in the middle of a component tree. We suggest to use a linter to prevent mistakes like forgetting a return statement before JSX.act warnings are now opt-in: If you’re running end-to-end tests, the act warnings are unnecessary. We’ve introduced an opt-in mechanism so you can enable them only for unit tests where they are useful and beneficial.setState on unmounted components: Previously, React warned about memory leaks when you call setState on an unmounted component. This warning was added for subscriptions, but people primarily run into it in scenarios where setting state is fine, and workarounds make the code worse. We’ve removed this warning.renderToString: Will no longer error when suspending on the server. Instead, it will emit the fallback HTML for the closest <Suspense> boundary and then retry rendering the same content on the client. It is still recommended that you switch to a streaming API like renderToPipeableStream or renderToReadableStream instead.renderToStaticMarkup: Will no longer error when suspending on the server. Instead, it will emit the fallback HTML for the closest <Suspense> boundary.You can view the full changelog here.
","excerpt":"As we shared in the release post, React 18 introduces features powered by our new concurrent renderer, with a gradual adoption strategy for existing applications. In this post, we will guide you through the steps for upgrading to React 18. Please report any issues you encounter while upgrading to React 18. Note for React Native users: React 18 will ship in a future version of React Native. This is because React 18 relies on the New React Native Architecture to benefit from the new capabilities…","frontmatter":{"title":"How to Upgrade to React 18","next":null,"prev":null,"author":[{"frontmatter":{"name":"Rick Hanlon","url":"https://twitter.com/rickhanlonii"}}]},"fields":{"date":"March 08, 2022","path":"content/blog/2022-03-08-react-18-upgrade-guide.md","slug":"/blog/2022/03/08/react-18-upgrade-guide.html"}},"allMarkdownRemark":{"edges":[{"node":{"frontmatter":{"title":"React Labs: What We've Been Working On – June 2022"},"fields":{"slug":"/blog/2022/06/15/react-labs-what-we-have-been-working-on-june-2022.html"}}},{"node":{"frontmatter":{"title":"React v18.0"},"fields":{"slug":"/blog/2022/03/29/react-v18.html"}}},{"node":{"frontmatter":{"title":"How to Upgrade to React 18"},"fields":{"slug":"/blog/2022/03/08/react-18-upgrade-guide.html"}}},{"node":{"frontmatter":{"title":"React Conf 2021 Recap"},"fields":{"slug":"/blog/2021/12/17/react-conf-2021-recap.html"}}},{"node":{"frontmatter":{"title":"The Plan for React 18"},"fields":{"slug":"/blog/2021/06/08/the-plan-for-react-18.html"}}},{"node":{"frontmatter":{"title":"Introducing Zero-Bundle-Size React Server Components"},"fields":{"slug":"/blog/2020/12/21/data-fetching-with-react-server-components.html"}}},{"node":{"frontmatter":{"title":"React v17.0"},"fields":{"slug":"/blog/2020/10/20/react-v17.html"}}},{"node":{"frontmatter":{"title":"Introducing the New JSX Transform"},"fields":{"slug":"/blog/2020/09/22/introducing-the-new-jsx-transform.html"}}},{"node":{"frontmatter":{"title":"React v17.0 Release Candidate: No New Features"},"fields":{"slug":"/blog/2020/08/10/react-v17-rc.html"}}},{"node":{"frontmatter":{"title":"React v16.13.0"},"fields":{"slug":"/blog/2020/02/26/react-v16.13.0.html"}}}]}},"pageContext":{"slug":"/blog/2022/03/08/react-18-upgrade-guide.html"}},"staticQueryHashes":[]}