react18-dep-compatibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Dependency Compatibility Matrix

React依赖兼容矩阵

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.

实现React 18.3.1和React 19兼容所需的各依赖最低版本。

当你需要检查依赖是否支持目标React版本、解决对等依赖冲突、决定是升级还是使用

legacy-peer-deps

，或是评估

react-router

v5升级到v6的迁移风险时，均可使用这份指南。

在React升级过程中执行

npm install

前，以及接受npm依赖冲突解决方案前，请先查看本矩阵，尤其是在可能影响并发模式兼容性的场景下。

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

包名	React 17 (当前版本)	React 18.3.1 (最低兼容版本)	React 19 (最低兼容版本)	备注
`react`	17.x	18.3.1	19.0.0	若使用React 18生态，请严格固定版本为18.3.1
`react-dom`	17.x	18.3.1	19.0.0	必须与react版本完全匹配

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

包名	React 18最低兼容版本	React 19最低兼容版本	备注
`@testing-library/react`	14.0.0	16.0.0	RTL 13内部使用ReactDOM.render，在React 18中无法正常运行
`@testing-library/jest-dom`	6.0.0	6.0.0	v5可正常使用，但v6新增了React 18匹配器更新
`@testing-library/user-event`	14.0.0	14.0.0	v13为同步逻辑，v14为异步逻辑，需要调整API调用方式
`jest`	27.x	27.x	React 18需使用jest 27+搭配jsdom 16+
`jest-environment-jsdom`	27.x	27.x	必须与jest版本匹配

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.

包名	React 18最低兼容版本	React 19最低兼容版本	备注
`@apollo/client`	3.8.0	3.11.0	3.8版本新增了 `useSyncExternalStore` 支持并发模式
`graphql`	15.x	16.x	Apollo 3.8+对等依赖要求graphql版本为15或16

请阅读**

references/apollo-details.md

**了解并发模式相关问题和MockedProvider的变更。

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 18最低兼容版本	React 19最低兼容版本	备注
`@emotion/react`	11.10.0	11.13.0	11.10版本新增React 18并发模式支持
`@emotion/styled`	11.10.0	11.13.0	必须与@emotion/react版本匹配
`@emotion/cache`	11.10.0	11.13.0	若直接使用该包需满足此版本要求

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

包名	React 18最低兼容版本	React 19最低兼容版本	备注
`react-router-dom`	v6.0.0	v6.8.0	v5升级到v6属于破坏性迁移，详见下文说明
`react-router-dom` v5	5.3.4 (临时兼容方案)	❌ 不支持	请查看legacy-peer-deps相关说明

react-router v5→v6是独立的迁移迭代任务，请阅读

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

包名	React 18最低兼容版本	React 19最低兼容版本	备注
`react-redux`	8.0.0	9.0.0	v7仅在React 18 legacy root下可运行，并发模式下会出错
`redux`	4.x	5.x	Redux本身不绑定框架，版本要求以react-redux为准
`@reduxjs/toolkit`	1.9.0	2.0.0	RTK 1.9已完成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

包名	React 18最低兼容版本	React 19最低兼容版本	备注
`react-query` / `@tanstack/react-query`	4.0.0	5.0.0	v3不支持并发模式
`react-hook-form`	7.0.0	7.43.0	v6存在并发模式兼容问题
`formik`	2.2.9	2.4.0	v2.2.9已修复React 18兼容问题
`react-select`	5.0.0	5.8.0	v4与React 18存在对等依赖冲突
`react-datepicker`	4.8.0	6.0.0	v4.8+新增React 18支持
`react-dnd`	16.0.0	16.0.0	v15及更低版本存在React 18并发模式兼容问题
`prop-types`	任意版本	任意版本	独立工具，不受React版本影响

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

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

--legacy-peer-deps使用规则

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.

仅在以下场景使用

--legacy-peer-deps

：

该包没有兼容React 18的发布版本
该包仍在积极维护（未被废弃）
冲突仅为对等依赖声明不匹配，而非实际API不兼容

请记录每一次
--legacy-peer-deps
的使用，在package.json顶部添加注释，或在MIGRATION.md文件中说明使用的必要性。