Next.js 15 + React 19

在 Next.js 15 与 React 19 中使用 shadcn/ui。

更新： 最新版 latest 已完整支持 React 19 与 Tailwind v4。本文可能存在过时信息，使用前请留意。

TL;DR

如果使用 npm，shadcn/ui 依赖需要配合参数安装。运行 CLI 时会提示选择相应参数；pnpm、bun、yarn 无需额外设置。

各依赖对 React 19 的兼容情况见 Upgrade Status。

发生了什么？

React 19 现已发布 RC，并且 Next.js 15 已完成测试与支持。

要兼容 React 19，依赖包需要将 React 19 添加为 peer dependency，目前各库正在陆续完成更新（例如 radix-ui、cmdk、vaul 等）。

"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"
},

可通过 npm info <package> peerDependencies 检查某个依赖是否已声明 React 19。

在依赖尚未声明 React 19 时，使用 npm 安装会看到类似错误：

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

注意： 该报错仅存在于 npm。pnpm 与 Bun 只会给出警告。

解决方案

方案一：使用 `--force` 或 `--legacy-peer-deps`

通过参数强制安装依赖：

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

这样可以忽略 peer dependency 校验。

方案二：暂时使用 React 18

将 react 和 react-dom 降级到 18，待依赖更新后再升级：

npm i react@18 react-dom@18

无论采用哪种方案，完成后务必充分测试应用，确保没有回归问题。

在 Next.js 15 中使用 shadcn/ui

使用 pnpm、bun 或 yarn

按照安装指南操作即可，无需额外参数。

使用 npm

运行 npx shadcn@latest init -d 时，CLI 会提示选择解决 peer dependency 的方案：

It 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

选择对应选项后，CLI 会带上参数执行。

添加组件

添加组件时流程与上面一致，选择对应参数即可。

请务必在安装新依赖后测试你的应用。

Upgrade Status

以下表格列出了 shadcn/ui 依赖对 React 19 的支持情况：

✅：在 npm、pnpm、bun 下均可正常使用。
🚧：pnpm、bun 可正常使用；npm 需手动加参数，相关 PR 正在推进。

Package	Status	Note
radix-ui	✅
lucide-react	✅
class-variance-authority	✅	仍未声明 React 19，为正常使用不受影响
tailwindcss-animate	✅	同上
embla-carousel-react	✅
recharts	✅	见下方 Recharts 说明
react-hook-form	✅
react-resizable-panels	✅
sonner	✅
react-day-picker	✅	npm 需加参数，正在推进 v9 升级
input-otp	✅
vaul	✅
@radix-ui/react-icons	✅	参考 PR #194
cmdk	✅

如有疑问，请在 GitHub 提交 issue。

Recharts

若要在 React 19 中使用 recharts，需要覆盖 react-is 版本：

在 `package.json` 中添加 overrides

package.json

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

注意：react-is 的版本需与实际使用的 React 19 版本一致，以上仅为示例。

执行安装命令


pnpm add --legacy-peer-deps

MCP Server Tailwind v4

本页内容

TL;DR 发生了什么？解决方案方案一：使用 --force 或 --legacy-peer-deps方案二：暂时使用 React 18 在 Next.js 15 中使用 shadcn/ui 使用 pnpm、bun 或 yarn 使用 npm 添加组件 Upgrade Status Recharts