Next.js 15 + React 19

TL;DR

如果你使用的是 npm，可以通过一个标志来安装 shadcn/ui 依赖。运行 shadcn CLI 时，它会提示你选择一个标志。pnpm、bun 和 yarn 不需要额外标志。

各个包对 React 19 的支持状态请查看 升级状态。

发生了什么？

React 19 现在已经是 rc，并且在 最新的 Next.js 15 版本中经过测试并得到支持。

为了支持 React 19，包维护者需要测试并更新他们的包，把 React 19 加入 peer dependency。这个过程已经在 进行中 radix-ui cmdk vaul。

Copy"peerDependencies": {
-  "react": "^16.8 || ^17.0 || ^18.0",
+  "react": "^16.8 || ^17.0 || ^18.0 || ^19.0",
-  "react-dom": "^16.8 || ^17.0 || ^18.0"
+  "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0"
},

为了支持 React 19，包维护者需要测试并更新他们的包，把 React 19 加入 peer dependency。你可以通过运行 npm info <package> peerDependencies 来检查某个包是否把 React 19 列为 peer dependency。

与此同时，如果你安装的包没有把 React 19 列为 peer dependency，你会看到类似下面的错误信息：

Copynpm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@0.1.0
npm error Found: react@19.0.0-rc-69d4b800-20241021
npm error node_modules/react
npm error   react@"19.0.0-rc-69d4b800-20241021" from the root project

如何修复

方案 1：--force 或 --legacy-peer-deps

你可以使用 --force 或 --legacy-peer-deps 标志强制安装包。

Copynpm i <package> --force
 
npm i <package> --legacy-peer-deps

这样会安装该包并忽略 peer dependency 警告。

方案 2：使用 React 18

你可以把 react 和 react-dom 降级到 18 版本，这与正在安装的包兼容；等依赖更新后再升级回来。

Copynpm i react@18 react-dom@18

无论你选择哪种方案，都务必充分测试应用，确保没有回归。

在 Next.js 15 中使用 shadcn/ui

使用 pnpm、bun 或 yarn

按照 安装指南 中的说明安装 shadcn/ui。无需额外标志。

使用 npm

当你运行 npx shadcn@latest init -d 时，系统会提示你选择一个选项来解决 peer dependency 问题。

CopyIt looks like you are using React 19.
Some packages may fail to install due to peer dependency issues (see https://ui.shadcn.com/react-19).
 
? How would you like to proceed? › - Use arrow-keys. Return to submit.
❯   Use --force
    Use --legacy-peer-deps

然后你就可以带着所选标志运行该命令。

添加组件

添加组件的过程与上面相同。选择一个标志来解决 peer dependency 问题。

记得在安装新依赖后始终测试你的应用。

升级状态

为了便于你跟踪升级进度，下面这张表展示了 shadcn/ui 依赖对 React 19 的支持状态。

• ✅ - 可在 npm、pnpm 和 bun 下与 React 19 一起工作。
• 🚧 - 可在 pnpm 和 bun 下与 React 19 一起工作。npm 需要加标志。PR 正在进行中。

如果你有任何问题，请在 GitHub 上 提交 issue。

Recharts

要在 React 19 下使用 recharts，你需要覆盖 react-is 依赖。

Copy"overrides": {
  "react-is": "^19.0.0-rc-69d4b800-20241021"
}