React18 Dep Compatibility

React Dependency Compatibility Matrix

Minimum versions required for React 18.3.1 and React 19 compatibility.

Use this skill whenever checking whether a dependency supports a target React version, resolving peer dependency conflicts, deciding whether to upgrade or use legacy-peer-deps, or assessing the risk of a react-router v5 to v6 migration.

Review this matrix before running npm install during a React upgrade and before accepting an npm dependency conflict resolution, especially where concurrent mode compatibility may be affected.

Core Upgrade Targets

Testing Libraries

Apollo Client

Read `references/apollo-details.md` for concurrent mode issues and MockedProvider changes.

Emotion

React Router

react-router v5 → v6 is a SEPARATE migration sprint. Read references/router-migration.md.

Redux

Other Common Packages

---

Conflict Resolution Decision Tree

npm ls shows peer conflict for package X
         │
         ▼
Does package X have a version that supports React 18?
  YES → npm install X@[min-compatible-version]
  NO  ↓
         │
Is the package critical to the app?
  YES → check GitHub issues for React 18 branch/fork
      → check if maintainer has a PR open
      → last resort: --legacy-peer-deps (document why)
  NO  → consider removing the package

--legacy-peer-deps Rules

Only use --legacy-peer-deps when:

• The package has no React 18 compatible release
• The package is actively maintained (not abandoned)
• The conflict is only a peer dep declaration mismatch (not actual API incompatibility)

Document every `--legacy-peer-deps` usage in a comment at the top of package.json or in a MIGRATION.md file explaining why it was necessary.

Apollo Client - React 18 Compatibility Details

Why Apollo 3.8+ is Required

Apollo Client 3.7 and below use an internal subscription model that is not compatible with React 18's concurrent rendering. In concurrent mode, React can interrupt and replay renders, which causes Apollo's store subscriptions to fire at incorrect times - producing stale data or missed updates.

Apollo 3.8 was the first version to adopt useSyncExternalStore, which React 18 requires for external stores to work correctly under concurrent rendering.

Version Summary

If You're on Apollo 3.7 Using Legacy Root

If the app still uses ReactDOM.render (legacy root) and hasn't migrated to createRoot yet, Apollo 3.7 will technically work - but this means you're not getting any React 18 concurrent features (including automatic batching). This is a partial upgrade only.

As soon as createRoot is used, upgrade Apollo to 3.8+.

MockedProvider in Tests - React 18

Apollo's MockedProvider works with React 18 but async behavior changed:

// Old pattern - flushing with setTimeout:
await new Promise(resolve => setTimeout(resolve, 0));
wrapper.update();

// React 18 pattern - use waitFor or findBy:
await waitFor(() => {
  expect(screen.getByText('Alice')).toBeInTheDocument();
});
// OR:
expect(await screen.findByText('Alice')).toBeInTheDocument();

Upgrading Apollo

npm install @apollo/client@latest graphql@latest

If graphql peer dep conflicts with other packages:

npm ls graphql  # check what version is being used
npm info @apollo/client peerDependencies  # check what apollo requires

Apollo 3.8+ supports both graphql@15 and graphql@16.

InMemoryCache - No Changes Required

InMemoryCache configuration is unaffected by the React 18 upgrade. No migration needed for:

• typePolicies
• fragmentMatcher
• possibleTypes
• Custom field policies

useQuery / useMutation / useSubscription - No Changes

Apollo hooks are unchanged in their API. The upgrade is entirely internal to how Apollo integrates with React's rendering model.

React Router v5 → v6 - Scope Assessment

Why This Is a Separate Sprint

React Router v5 → v6 is a complete API rewrite. Unlike most React 18 upgrade steps which touch individual patterns, the router migration affects:

• Every <Route> component
• Every <Switch> (replaced by <Routes>)
• Every useHistory() (replaced by useNavigate())
• Every useRouteMatch() (replaced by useMatch())
• Every <Redirect> (replaced by <Navigate>)
• Nested route definitions (entirely new model)
• Route parameters access
• Query string handling

Attempting this as part of the React 18 upgrade sprint will scope-creep the migration significantly.

Recommended Approach

Option A - Defer Router Migration (Recommended)

Use react-router-dom@5.3.4 with --legacy-peer-deps during the React 18 upgrade. This is explicitly documented as a supported workaround by the react-router team for React 18 compatibility on legacy root.

# In the React 18 dep surgeon:
npm install react-router-dom@5.3.4 --legacy-peer-deps

Document in package.json:

"_legacyPeerDepsReason": {
  "react-router-dom@5.3.4": "Router v5→v6 migration deferred to separate sprint. React 18 peer dep mismatch only - no API incompatibility on legacy root."
}

Then schedule the v5 → v6 migration as its own sprint after the React 18 upgrade is stable.

Option B - Migrate Router as Part of React 18 Sprint

Only choose this if:

• The app has minimal routing (< 10 routes, no nested routes, no complex navigation logic)
• The team has bandwidth and the sprint timeline allows it

Scope Assessment Scan

Run this to understand the router migration scope before deciding:

echo "=== Route definitions ==="
grep -rn "<Route\|<Switch\|<Redirect" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== useHistory calls ==="
grep -rn "useHistory()" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== useRouteMatch calls ==="
grep -rn "useRouteMatch()" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== withRouter HOC ==="
grep -rn "withRouter" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== history.push / history.replace ==="
grep -rn "history\.push\|history\.replace\|history\.go" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

Decision guide:

• Total hits < 30 → router migration is feasible in this sprint
• Total hits 30–100 → strongly recommend deferring
• Total hits > 100 → must defer - separate sprint required

v5 → v6 API Changes Summary