Next.js 15 + React 19

TL;DR

如果你使用的是 npm，你可以使用标志安装 shadcn/ui 依赖。shadcn CLI 将提示你在运行时选择一个标志。pnpm、bun 或 yarn 不需要标志。

¥If you're using npm, you can install shadcn/ui dependencies with a flag. The shadcn CLI will prompt you to select a flag when you run it. No flags required for pnpm, bun, or yarn.

请参阅 升级状态 了解每个包对 React 19 的支持状态。

¥See Upgrade Status for the status of React 19 support for each package.

发生了什么？

¥What's happening?

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

¥React 19 is now rc and is tested and supported in the latest Next.js 15 release.

要支持 React 19，软件包维护者需要测试和更新他们的软件包以将 React 19 作为对等依赖包含在内。这是 already in progress。

¥To support React 19, package maintainers will need to test and update their packages to include React 19 as a peer dependency. This is already in progress.

"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 列为对等依赖，你将看到如下错误消息：

¥In the meantime, if you are installing a package that does not list React 19 as a peer dependency, you will see an error message like this:

npm 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

如何解决此问题

¥How to fix this

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

¥Solution 1: --force or --legacy-peer-deps

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

¥You can force install a package with the --force or the --legacy-peer-deps flag.

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

这将安装包并忽略对等依赖警告。

¥This will install the package and ignore the peer dependency warnings.

解决方案 2：使用 React 18

¥Solution 2: Use React 18

你可以将 react 和 react-dom 降级到版本 18，该版本与你正在安装的包兼容，并在依赖更新时升级。

¥You can downgrade react and react-dom to version 18, which is compatible with the package you are installing and upgrade when the dependency is updated.

npm i react@18 react-dom@18

无论你选择哪种解决方案，请务必彻底测试你的应用以确保没有回归。

¥Whichever solution you choose, make sure you test your app thoroughly to ensure there are no regressions.

在 Next.js 15 上使用 shadcn/ui

¥Using shadcn/ui on Next.js 15

使用 pnpm、bun 或 yarn

¥Using pnpm, bun, or yarn

按照 安装指南 中的说明安装 shadcn/ui。不需要标记。

¥Follow the instructions in the installation guide to install shadcn/ui. No flags are needed.

使用 npm

¥Using npm

当你运行 npx shadcn@latest init -d 时，系统将提示你选择一个选项来解决对等依赖问题。

¥When you run npx shadcn@latest init -d, you will be prompted to select an option to resolve the peer dependency issues.

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

然后你可以使用你选择的标志运行命令。

¥You can then run the command with the flag you choose.

添加组件

¥Adding components

添加组件的过程与上述相同。选择一个标志来解决对等依赖问题。

¥The process for adding components is the same as above. Select a flag to resolve the peer dependency issues.

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

¥Remember to always test your app after installing new dependencies.

升级状态

¥Upgrade Status

为了方便你跟踪升级进度，我在下面创建了一个表格，其中包含 shadcn/ui 依赖的 React 19 支持状态。

¥To make it easy for you track the progress of the upgrade, I've created a table below with React 19 support status for the shadcn/ui dependencies.

• ✅ - 使用 npm、pnpm 和 bun 与 React 19 配合使用。

  ¥✅ - Works with React 19 using npm, pnpm, and bun.

• 🚧 - 使用 pnpm 和 bun 与 React 19 配合使用。需要 npm 标志。PR 正在进行中。

  ¥🚧 - Works with React 19 using pnpm and bun. Requires flag for npm. PR is in progress.

如果你有任何疑问，请在 GitHub 上联系 打开问题。

¥If you have any questions, please open an issue on GitHub.

Recharts

要将 recharts 与 React 19 一起使用，你需要覆盖 react-is 依赖。

¥To use recharts with React 19, you will need to override the react-is dependency.

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