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

Package	React 17 (current)	React 18.3.1 (min)	React 19 (min)	Notes
`react`	17.x	18.3.1	19.0.0	Pin exactly to 18.3.1 for the R18 orchestra
`react-dom`	17.x	18.3.1	19.0.0	Must match react version exactly

Testing Libraries

Package	React 18 Min	React 19 Min	Notes
`@testing-library/react`	14.0.0	16.0.0	RTL 13 uses ReactDOM.render internally - broken in R18
`@testing-library/jest-dom`	6.0.0	6.0.0	v5 works but v6 has React 18 matcher updates
`@testing-library/user-event`	14.0.0	14.0.0	v13 is sync, v14 is async - API change required
`jest`	27.x	27.x	jest 27+ with jsdom 16+ for React 18
`jest-environment-jsdom`	27.x	27.x	Must match jest version

Apollo Client

Package	React 18 Min	React 19 Min	Notes
`@apollo/client`	3.8.0	3.11.0	3.8 adds `useSyncExternalStore` for concurrent mode
`graphql`	15.x	16.x	Apollo 3.8+ peer requires graphql 15 or 16

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

Emotion

Package	React 18 Min	React 19 Min	Notes
`@emotion/react`	11.10.0	11.13.0	11.10 adds React 18 concurrent mode support
`@emotion/styled`	11.10.0	11.13.0	Must match @emotion/react version
`@emotion/cache`	11.10.0	11.13.0	If used directly

React Router

Package	React 18 Min	React 19 Min	Notes
`react-router-dom`	v6.0.0	v6.8.0	v5 → v6 is a breaking migration - see details below
`react-router-dom` v5	5.3.4 (workaround)	❌ Not supported	See legacy peer deps note

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

Redux

Package	React 18 Min	React 19 Min	Notes
`react-redux`	8.0.0	9.0.0	v7 works on R18 legacy root only - breaks on concurrent mode
`redux`	4.x	5.x	Redux itself is framework-agnostic - react-redux version matters
`@reduxjs/toolkit`	1.9.0	2.0.0	RTK 1.9 tested against React 18

Other Common Packages

Package	React 18 Min	React 19 Min	Notes
`react-query` / `@tanstack/react-query`	4.0.0	5.0.0	v3 doesn't support concurrent mode
`react-hook-form`	7.0.0	7.43.0	v6 has concurrent mode issues
`formik`	2.2.9	2.4.0	v2.2.9 patched for React 18
`react-select`	5.0.0	5.8.0	v4 has peer dep conflicts with R18
`react-datepicker`	4.8.0	6.0.0	v4.8+ added React 18 support
`react-dnd`	16.0.0	16.0.0	v15 and below have R18 concurrent mode issues
`prop-types`	any	any	Standalone - unaffected by React version

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.

React Dependency Compatibility Matrix

Minimum versions required for React 18.3.1 and React 19 compatibility.

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

Package	React 17 (current)	React 18.3.1 (min)	React 19 (min)	Notes
`react`	17.x	18.3.1	19.0.0	Pin exactly to 18.3.1 for the R18 orchestra
`react-dom`	17.x	18.3.1	19.0.0	Must match react version exactly

Testing Libraries

Package	React 18 Min	React 19 Min	Notes
`@testing-library/react`	14.0.0	16.0.0	RTL 13 uses ReactDOM.render internally - broken in R18
`@testing-library/jest-dom`	6.0.0	6.0.0	v5 works but v6 has React 18 matcher updates
`@testing-library/user-event`	14.0.0	14.0.0	v13 is sync, v14 is async - API change required
`jest`	27.x	27.x	jest 27+ with jsdom 16+ for React 18
`jest-environment-jsdom`	27.x	27.x	Must match jest version

Apollo Client

Package	React 18 Min	React 19 Min	Notes
`@apollo/client`	3.8.0	3.11.0	3.8 adds `useSyncExternalStore` for concurrent mode
`graphql`	15.x	16.x	Apollo 3.8+ peer requires graphql 15 or 16

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

Emotion

Package	React 18 Min	React 19 Min	Notes
`@emotion/react`	11.10.0	11.13.0	11.10 adds React 18 concurrent mode support
`@emotion/styled`	11.10.0	11.13.0	Must match @emotion/react version
`@emotion/cache`	11.10.0	11.13.0	If used directly

React Router

Package	React 18 Min	React 19 Min	Notes
`react-router-dom`	v6.0.0	v6.8.0	v5 → v6 is a breaking migration - see details below
`react-router-dom` v5	5.3.4 (workaround)	❌ Not supported	See legacy peer deps note

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

Redux

Package	React 18 Min	React 19 Min	Notes
`react-redux`	8.0.0	9.0.0	v7 works on R18 legacy root only - breaks on concurrent mode
`redux`	4.x	5.x	Redux itself is framework-agnostic - react-redux version matters
`@reduxjs/toolkit`	1.9.0	2.0.0	RTK 1.9 tested against React 18

Other Common Packages

Package	React 18 Min	React 19 Min	Notes
`react-query` / `@tanstack/react-query`	4.0.0	5.0.0	v3 doesn't support concurrent mode
`react-hook-form`	7.0.0	7.43.0	v6 has concurrent mode issues
`formik`	2.2.9	2.4.0	v2.2.9 patched for React 18
`react-select`	5.0.0	5.8.0	v4 has peer dep conflicts with R18
`react-datepicker`	4.8.0	6.0.0	v4.8+ added React 18 support
`react-dnd`	16.0.0	16.0.0	v15 and below have R18 concurrent mode issues
`prop-types`	any	any	Standalone - unaffected by React version

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.