Migration Guides
React 15→16, 16→17, 17→18, and 18→19: what breaks, what is optional, checklists, and common mistakes. · 5 lessons · click a card to expand
Part of the React 16 → 19.3 evolution reference. Expand a card, then use chapter links in the sidebar.
Codemods exist (npx types-react-codemod, React 19 upgrade guide). This page is the why and the checklist, not a substitute for the official React 19 Upgrade Guide.
15 → 16
1 item01React 15 to 16: new engine, mostly compatibleReact 16
What changed
- Fiber
- Error Boundaries, Portals, fragments
React.createClassalready gone (useclass)- Unknown DOM attributes passed through
- Rendering
null, arrays, strings from components more freely
What breaks
- Anything that reached into private React internals
- Addons that assumed the stack reconciler
- Some
ReactDOM.rendercallbacks timing - Tests using removed test utils
Before / after
// 15: extra wrapper everywhere
return <div>{a}{b}</div>;
// 16.2
return <>{a}{b}</>;Checklist
- [ ] Upgrade
reactandreact-domtogether (always) - [ ] Upgrade
react-addons-*off deprecated addons - [ ] Add an Error Boundary at the route shell
- [ ] Run the app; look for console warnings
- [ ] Replace
React.createClassif any remain
Common mistakes
Upgrading react without react-dom (invalid hook / dispatcher errors).
Optional vs required
Required to receive any later feature. 15 is unmaintained.
16 → 17
1 item02React 16 to 17: low-drama infrastructureReact 17
What changed
- Event delegation on the root
- New JSX transform (or keep classic)
- Event pooling gone (
e.persistunnecessary) - Effect cleanup ordering
What breaks
- Homemade click-outside that assumed document-level React 16 ordering
- Microfrontends that depended on two Reacts fighting on
document(they may start working) - Classic JSX + deleted
import Reacttoo early
Before / after JSX
// tsconfig
{ "compilerOptions": { "jsx": "react-jsx" } }Checklist
- [ ]
react+react-dom17 - [ ] Turn on automatic JSX runtime when ready
- [ ] Search
e.persistand delete - [ ] QA dropdowns, modals, nested apps
- [ ] ESLint: disable
react/react-in-jsx-scopeif using the new transform
Optional vs required
Upgrade is strongly recommended. New JSX transform is optional but cheap (also works on 16.14).
ReactDOM.render. Concurrent APIs wait until 18.createRoot into this PR.17 → 18
1 item03React 17 to 18: new root, batching, Strict ModeReact 18
createRoot, automatic batching, Strict Mode double-invoking effects, hydration warnings.What changed
createRoot/hydrateRoot- Automatic batching in promises/timeouts
- Concurrent features available
- Strict Mode remount check in development
- Streaming SSR APIs
What breaks
- Impure render (will surface)
- Effects without cleanup (double fetch in dev)
- Libraries using
ReactDOM.renderinternally - Code that depended on two paints in a
.then(batching now one paint) - TypeScript types (
@types/react18)
Before / after bootstrap
// 17
ReactDOM.render(
<StrictMode>
<App />
</StrictMode>,
document.getElementById("root"),
);
// 18
createRoot(document.getElementById("root")).render(
<StrictMode>
<App />
</StrictMode>,
);Checklist
- [ ] Upgrade types
- [ ] Replace
render/hydratewithcreateRoot/hydrateRoot(strongly recommended; required for 19) - [ ] Fix Strict Mode double-effect (abort fetches, close sockets)
- [ ] Search
UNSAFE_,findDOMNode, string refs (warnings) - [ ] QA forms that set two states after
await - [ ] If SSR: switch to streaming when the framework supports it
Optional vs required
createRoot: strongly recommended in 18; required to get concurrent APIs; required in 19useTransitionin app code: optional until you have a janky view- Staying on
ReactDOM.renderin 18: allowed with warning, not a good idea
Common mistakes
- “I’ll skip createRoot until we need Transitions” then upgrading to 19 in a panic
- Disabling Strict Mode to hide double fetch
useId / transitions where needed.createRoot, log render counts around an async submit — they should drop.18 → 19
2 items04React 18 to 19: removals plus ActionsReact 19
use(). Required removals make this a real breaking major. Follow the official upgrade guide.What changed (features)
- Actions,
useActionState,useFormStatus,useOptimistic,use() - Ref as prop, Context as
<Context> - Document metadata / resources
- Better hydration errors
What breaks (removals)
ReactDOM.render/hydratefindDOMNode- String refs
- Legacy context
- Old lifecycles (
componentWillMountwithout having migrated) - Function
defaultProps - Some
react-test-renderer/actimport paths - Children as a prop in some secret ways;
element.props.refaccess patterns — see upgrade guide - TypeScript:
JSXnamespace moves; refs on functions
Before / after defaultProps
function Icon({ size = 16 }) {
return <svg width={size} height={size} />;
}Checklist
- [ ] Be on 18 createRoot first (do not 17 → 19)
- [ ] Run official codemods
- [ ] Delete
ReactDOM.render - [ ] Replace function
defaultProps - [ ] Grep
findDOMNode,contextTypes,componentWillMount - [ ] Upgrade
react-dompeer packages (router, query, styled-components) - [ ] Fix new TypeScript errors (
Ref,ReactNode) - [ ] QA hydration messages (they are stricter / clearer)
- [ ] Optionally adopt Actions on one form as a pilot
Optional vs required
| Item | 18→19 |
|---|---|
| createRoot | Required (legacy root gone) |
| Rewrite all forms to Actions | Optional |
use() everywhere | Optional |
Remove forwardRef | Optional |
| Function defaultProps | Required if you had them |
Common mistakes
- Upgrading
react19 with a library that still callsReactDOM.render - Using
useFormState(old name) — it isuseActionState - Expecting RSC in a Vite SPA after the 19 bump
190 → 19.1 → 19.2 → 19.3
- 19.1: Owner Stack,
useIdformat — recommended, watch E2E selectors - 19.2: Activity,
useEffectEvent— recommended; adopt APIs as needed - 19.3: ViewTransition, Fragment refs — recommended if you animate; not mandatory to use the APIs
Tip: Never skip 18. Go 17 → 18 (createRoot) → 19.
Try it: A dry-run npm i react@19 react-dom@19 on a branch and fix compile errors before runtime QA.
npm i react@19 react-dom@19 on a branch and fix compile errors before runtime QA.