Next.js 15 + React 19
在 Next.js 15 和 React 19 中使用 shadcn/ui。
更新: 我们在 canary
版本中已添加了对 React 19 和 Tailwind v4 的全面支持。请查看 Tailwind v4 文档以获取更多信息。
以下指南适用于任何支持 React 19 的框架。我将此页面命名为 "Next.js 15 + React 19",以便帮助升级到 Next.js 15 的人找到它。我们正在与包维护者合作,帮助升级到 React 19。
简而言之
如果你使用的是 npm
,可以通过添加标志来安装 shadcn/ui 依赖项。运行 shadcn
CLI 时,它会提示你选择一个标志。对于 pnpm、bun 或 yarn 不需要标志。
请查看 升级状态 以了解每个包对 React 19 支持的状态。
发生了什么?
React 19 现已达到 rc 阶段,并且在 最新的 Next.js 15 版本中经过测试和支持。
为了支持 React 19,包维护者需要测试并更新他们的包,将 React 19 包含为对等依赖。这一工作 已经 在 进行中。
"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 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 只会显示一个无声警告。
如何解决这个问题
解决方案 1:--force
或 --legacy-peer-deps
你可以使用 --force
或 --legacy-peer-deps
标志强制安装包。
npm i <package> --force
npm i <package> --legacy-peer-deps
这将安装包并忽略对等依赖警告。
解决方案 2:使用 React 18
你可以将 react
和 react-dom
降级到与你安装的包兼容的版本 18,并在依赖更新时再升级。
npm i react@18 react-dom@18
无论你选择哪种解决方案,请务必彻底测试你的应用,以确保没有回归问题。
在 Next.js 15 上使用 shadcn/ui
使用 pnpm、bun 或 yarn
按照 安装指南 中的说明安装 shadcn/ui。不需要标志。
使用 npm
当你运行 npx shadcn@latest init -d
时,会提示你选择一个选项来解决对等依赖问题。
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
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
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.
- ✅ - Works with React 19 using npm, pnpm, and bun.
- 🚧 - Works with React 19 using pnpm and bun. Requires flag for npm. PR is in progress.
Package | Status | Note |
---|---|---|
radix-ui | ✅ | |
lucide-react | ✅ | |
class-variance-authority | ✅ | Does not list React 19 as a peer dependency. |
tailwindcss-animate | ✅ | Does not list React 19 as a peer dependency. |
embla-carousel-react | ✅ | |
recharts | ✅ | See note below |
react-hook-form | ✅ | |
react-resizable-panels | ✅ | |
sonner | ✅ | |
react-day-picker | ✅ | Works with flag for npm. Work to upgrade to v9 in progress. |
input-otp | ✅ | |
vaul | ✅ | |
@radix-ui/react-icons | 🚧 | See PR #194 |
cmdk | ✅ |
If you have any questions, please open an issue on GitHub.
Recharts
To use recharts with React 19, you will need to override the react-is
dependency.
Add the following to your package.json
"overrides": {
"react-is": "^19.0.0-rc-69d4b800-20241021"
}
Note: the react-is
version needs to match the version of React 19 you are using. The above is an example.