Summary

This guide summarizes the practical steps to upgrade apps to React 18: install the new package, migrate client and server rendering APIs, update TypeScript types, handle testing and Strict Mode changes, and take advantage of automatic batching and new hooks. Follow the checklist below to perform a safe, incremental upgrade.

Key Points

• Install:

  • npm: npm install react react-dom
  • yarn: yarn add react react-dom

• Migrate client APIs:

  • Replace ReactDOM.render with createRoot:
    • const root = createRoot(container); root.render(<App />)
  • Replace unmountComponentAtNode with root.unmount().
  • Replace server hydration hydrate with hydrateRoot for SSR.

• Server rendering:

  • Use renderToPipeableStream (Node) and renderToReadableStream (edge) for streaming with Suspense.
  • renderToString and renderToStaticMarkup have limited Suspense support; renderToNodeStream is deprecated.

• Automatic batching:

  • With createRoot, updates are batched across async boundaries (timeouts, promises, native events).
  • Opt out with flushSync from react-dom when needed.

• TypeScript changes:

  • Update @types/react and @types/react-dom to latest versions.
  • children often must be declared explicitly in props; run the provided migration script and fix type errors.

• New library hooks/APIs:

  • useSyncExternalStore (for external stores), useInsertionEffect (CSS-in-JS), and concurrent helpers like startTransition, useDeferredValue, useId.

• Strict Mode (dev-only):

  • React 18's Strict Mode simulates unmount/mount to reveal effects that assume single mount. If you hit failures, temporarily remove or scope StrictMode while fixing issues before re-enabling it.

• Testing:

  • Set globalThis.IS_REACT_ACT_ENVIRONMENT = true in your test setup to enable proper act(...) behavior with createRoot.

• Browser support:

  • React 18 drops Internet Explorer support; plan polyfills or browser support updates accordingly.

Follow these steps incrementally: migrate roots, run tests, update types, then opt into concurrent features when ready.