react ^17.0.2 → 18.3.1

01Risk & priority

Which files matter most, scored from concrete API evidence.

1. 90 src/legacy/toast.jsx react-bc-1 +40, react-bc-8 +20, root bootstrap +30
2. 90 src/legacy/toast.test.jsx react-bc-1 +40, react-bc-3 +20, react-bc-12 +10, test harness +20
3. 80 src/index.jsx react-bc-1 +40, react-bc-6 +10, root bootstrap +30
4. 70 src/ssr-entry.jsx react-bc-2 +40, root bootstrap +30
5. 20 src/App.jsx react-bc-4 +20
6. 20 src/components/AddItemForm.jsx react-bc-4 +20
7. 20 src/components/ItemList.jsx react-bc-4 +20
8. 20 src/components/SyncStatus.jsx react-bc-4 +20

02Breaking changes

The rules that apply to this repository — and why.

03Compatibility

Declared packages whose peer ranges could block the install.

Checked 602 packages via package-lock.json (lockfileVersion 3).

04Migration plan

What will change, in order, and what has happened so far.

Estimated effort HIGH · 10 steps · 4 applied automatically · 0 completed manually

1. 1
   Update react, react-dom, @testing-library/react to 18.3.1 and install

   Applied automatically config automated 2 files commit 798ad60

   • react ^17.0.2 → ^18.3.1
   • react-dom ^17.0.2 → ^18.3.1 (companion)
   • @testing-library/react ^12.1.5 → ^14.3.1 (peer-compat)

   Ran npm install --no-audit --no-fund; installed react@18.3.1, react-dom@18.3.1.

2. 2
   ReactDOM.render() is deprecated in React 18 (the app keeps running in legacy React 17 mode) — replace with createRoot().render()

   Applied automatically codemod automated 3 files commit 72cea40

   Transformed 3 file(s); no remaining usages of the old API.

3. 3
   ReactDOM.hydrate() is deprecated in React 18 (legacy mode) — replace with hydrateRoot()

   Applied automatically codemod automated 1 file commit 148d1eb

   Transformed 1 file(s); no remaining usages of the old API.

4. 4
   act() from react-dom/test-utils is deprecated — import act from 'react' (available from React 18.3)

   Applied automatically codemod automated 1 file commit f8756bf

   Transformed 1 file(s); no remaining usages of the old API.

5. 5
   Automatic batching: setState calls in timeouts/promises/native handlers are now batched — may affect code or tests relying on intermediate renders

   Manual action required manual human 4 files

   No automated change exists for this rule. Review any tests that assert on intermediate render states inside setTimeout, Promise.then, or native event handlers. Wrap those assertions in act() or use flushSync from 'react-dom' to opt out of automatic batching where needed.

6. 6
   ReactDOM.unmountComponentAtNode() is deprecated in React 18 — call root.unmount() on the root returned by createRoot()

   Manual action required manual human 1 file

   No automated change exists for this rule. Keep the root returned by createRoot(container) and call root.unmount() instead of unmountComponentAtNode(container). In tests, unmount the root the test created (React Testing Library unmounts automatically).

7. 7
   Strict Mode now double-invokes effects (mount → unmount → mount) in development to surface side effects

   Manual action required manual human 1 file

   No automated change exists for this rule. Audit useEffect, useLayoutEffect, and class lifecycle methods for non-idempotent side effects (network requests, analytics calls, subscriptions). Ensure cleanup functions are implemented so double-invocation does not cause observable problems in development.

8. 8
   ReactDOM.unstable_batchedUpdates is redundant under React 18 automatic batching

   Manual action required manual human 1 file

   No automated change exists for this rule. With React 18's automatic batching, explicit calls to unstable_batchedUpdates are no longer needed in most cases. Remove them and verify behaviour. If you need to force synchronous rendering, use flushSync from 'react-dom' instead.

9. 9
   Tests that render with react-dom directly need globalThis.IS_REACT_ACT_ENVIRONMENT = true under React 18

   Manual action required manual human 1 file

   No automated change exists for this rule. In the test setup file (e.g. setupTests.js / jest.setup.js), set globalThis.IS_REACT_ACT_ENVIRONMENT = true; so React 18 knows it runs in an act-aware test environment. React Testing Library ≥ 13 sets this automatically for tests that use it.

10. 10
    Update and verify tests

    Manual action required test human 3 files

    No automated test changes are made. Update tests if needed, run verify_migration, then record with markManualComplete.

05Affected files

Every file that uses the package family, with line-level evidence.

11 files

06Changes

Each step's commit on the migration branch.

6 files changed on codebase-doctor/react-18.3.1-upgrade since main.

 package-lock.json | 83 ++++++++++++++++++++++++-------------------------------
 package.json      |  6 ++--
 2 files changed, 39 insertions(+), 50 deletions(-)

diff --git a/package-lock.json b/package-lock.json@@ lockfile diff omitted: +36 −47 lines @@diff --git a/package.json b/package.jsonindex 3712010..20c83d0 100644--- a/package.json+++ b/package.json@@ -10,14 +10,14 @@     "lint": "eslint src"   },   "dependencies": {-    "react": "^17.0.2",-    "react-dom": "^17.0.2"+    "react": "^18.3.1",+    "react-dom": "^18.3.1"   },   "devDependencies": {     "@babel/core": "^7.24.0",     "@babel/preset-env": "^7.24.0",     "@babel/preset-react": "^7.24.0",-    "@testing-library/react": "^12.1.5",+    "@testing-library/react": "^14.3.1",     "babel-jest": "^29.7.0",     "esbuild": "^0.23.0",     "eslint": "^9.9.0",

 src/index.jsx             | 7 +++----
 src/legacy/toast.jsx      | 3 ++-
 src/legacy/toast.test.jsx | 4 ++--
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/index.jsx b/src/index.jsxindex c1f31c5..8e50ea1 100644--- a/src/index.jsx+++ b/src/index.jsx@@ -1,10 +1,9 @@ import React from 'react';-import ReactDOM from 'react-dom';+import { createRoot } from 'react-dom/client'; import App from './App'; -ReactDOM.render(+createRoot(document.getElementById('root')).render(   <React.StrictMode>     <App />-  </React.StrictMode>,-  document.getElementById('root')+  </React.StrictMode> );diff --git a/src/legacy/toast.jsx b/src/legacy/toast.jsxindex 6fc7919..ef8f0f5 100644--- a/src/legacy/toast.jsx+++ b/src/legacy/toast.jsx@@ -1,5 +1,6 @@ import React from 'react'; import ReactDOM from 'react-dom';+import { createRoot } from 'react-dom/client';  function Toast({ message }) {   return (@@ -14,7 +15,7 @@ function Toast({ message }) { export function showToast(message, ms = 3000) {   const host = document.createElement('div');   document.body.appendChild(host);-  ReactDOM.render(<Toast message={message} />, host);+  createRoot(host).render(<Toast message={message} />);   setTimeout(() => {     ReactDOM.unmountComponentAtNode(host);     host.remove();diff --git a/src/legacy/toast.test.jsx b/src/legacy/toast.test.jsxindex fe5b58c..6d09d4e 100644--- a/src/legacy/toast.test.jsx+++ b/src/legacy/toast.test.jsx@@ -1,5 +1,5 @@ import React from 'react';-import ReactDOM from 'react-dom';+import { createRoot } from 'react-dom/client'; import { act } from 'react-dom/test-utils'; import { showToast } from './toast'; @@ -25,7 +25,7 @@ test('toasts can render inside an existing tree', () => {   const container = document.createElement('div');   document.body.appendChild(container);   act(() => {-    ReactDOM.render(<p>host</p>, container);+    createRoot(container).render(<p>host</p>);   });   expect(container.textContent).toBe('host'); });

 src/ssr-entry.jsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/ssr-entry.jsx b/src/ssr-entry.jsxindex d20be01..91718cd 100644--- a/src/ssr-entry.jsx+++ b/src/ssr-entry.jsx@@ -1,6 +1,6 @@ import React from 'react';-import ReactDOM from 'react-dom';+import { hydrateRoot } from 'react-dom/client'; import App from './App';  // Entry used when the page is server-rendered: attach to the existing markup.-ReactDOM.hydrate(<App />, document.getElementById('root'));+hydrateRoot(document.getElementById('root'), <App />);

 src/legacy/toast.test.jsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/legacy/toast.test.jsx b/src/legacy/toast.test.jsxindex 6d09d4e..225ce96 100644--- a/src/legacy/toast.test.jsx+++ b/src/legacy/toast.test.jsx@@ -1,6 +1,6 @@ import React from 'react'; import { createRoot } from 'react-dom/client';-import { act } from 'react-dom/test-utils';+import { act } from 'react'; import { showToast } from './toast';  afterEach(() => {

07Verification

Does the upgraded code pass the repository's own checks?

08Remaining work

What still needs a human before (or after) merging.

• Manual action requiredstep-5-react-bc-4

  Automatic batching: setState calls in timeouts/promises/native handlers are now batched — may affect code or tests relying on intermediate renders

  Review any tests that assert on intermediate render states inside setTimeout, Promise.then, or native event handlers. Wrap those assertions in act() or use flushSync from 'react-dom' to opt out of automatic batching where needed.

• Manual action requiredstep-6-react-bc-8

  ReactDOM.unmountComponentAtNode() is deprecated in React 18 — call root.unmount() on the root returned by createRoot()

  Keep the root returned by createRoot(container) and call root.unmount() instead of unmountComponentAtNode(container). In tests, unmount the root the test created (React Testing Library unmounts automatically).

• Manual action requiredstep-7-react-bc-6

  Strict Mode now double-invokes effects (mount → unmount → mount) in development to surface side effects

  Audit useEffect, useLayoutEffect, and class lifecycle methods for non-idempotent side effects (network requests, analytics calls, subscriptions). Ensure cleanup functions are implemented so double-invocation does not cause observable problems in development.

• Manual action requiredstep-8-react-bc-7

  ReactDOM.unstable_batchedUpdates is redundant under React 18 automatic batching

  With React 18's automatic batching, explicit calls to unstable_batchedUpdates are no longer needed in most cases. Remove them and verify behaviour. If you need to force synchronous rendering, use flushSync from 'react-dom' instead.

• Manual action requiredstep-9-react-bc-12

  Tests that render with react-dom directly need globalThis.IS_REACT_ACT_ENVIRONMENT = true under React 18

  In the test setup file (e.g. setupTests.js / jest.setup.js), set globalThis.IS_REACT_ACT_ENVIRONMENT = true; so React 18 knows it runs in an act-aware test environment. React Testing Library ≥ 13 sets this automatically for tests that use it.

• Manual action requiredstep-10-tests

  Update and verify tests

  Update any test utilities that changed in the new version, then confirm the full suite passes with verify_migration. This step makes no automated source changes.

09Metrics

Measured values, labelled estimates, and what is not measured.

10Repository

How the repository was analysed.