mirror of
https://github.com/shadcn-ui/ui.git
synced 2026-06-15 20:01:35 +00:00
cdfecd1d97
* Revert "feat: remove npm flags (#5686)"
This reverts commit 4ff64ba818.
* chore: temporarily bring back flag
169 lines
7.3 KiB
Plaintext
169 lines
7.3 KiB
Plaintext
---
|
||
title: Next.js 15 + React 19
|
||
description: Using shadcn/ui with Next.js 15 and React 19.
|
||
---
|
||
|
||
<Callout>
|
||
**The following guide applies to any framework that supports React 19**. I
|
||
titled this page "Next.js 15 + React 19" to help people upgrading to Next.js
|
||
15 find it. We are working with package maintainers to help upgrade to React
|
||
19.
|
||
</Callout>
|
||
|
||
## TL;DR
|
||
|
||
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.
|
||
|
||
See [Upgrade Status](#upgrade-status) for the status of React 19 support for each package.
|
||
|
||
## What's happening?
|
||
|
||
React 19 is now [rc](https://www.npmjs.com/package/react?activeTab=versions) and is [tested and supported in the latest Next.js 15 release](https://nextjs.org/blog/next-15#react-19).
|
||
|
||
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](https://github.com/radix-ui/primitives/pull/2952) [in](https://github.com/pacocoursey/cmdk/pull/318) [progress](https://github.com/emilkowalski/vaul/pull/498).
|
||
|
||
```diff /^19.0/
|
||
"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"
|
||
},
|
||
```
|
||
|
||
<Callout>
|
||
You can check if a package lists React 19 as a peer dependency by running
|
||
`npm info <package> peerDependencies`.
|
||
</Callout>
|
||
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
<Callout>
|
||
**Note:** This is npm only. PNPM and Bun will only show a silent warning.
|
||
</Callout>
|
||
|
||
## How to fix this
|
||
|
||
### Solution 1: `--force` or `--legacy-peer-deps`
|
||
|
||
You can force install a package with the `--force` or the `--legacy-peer-deps` flag.
|
||
|
||
```bash
|
||
npm i <package> --force
|
||
|
||
npm i <package> --legacy-peer-deps
|
||
```
|
||
|
||
This will install the package and ignore the peer dependency warnings.
|
||
|
||
<Accordion type="multiple">
|
||
<AccordionItem value="flags">
|
||
<AccordionTrigger className="font-medium">
|
||
What do the `--force` and `--legacy-peer-deps` flag do?
|
||
</AccordionTrigger>
|
||
<AccordionContent className="[&_ul]:mt-0">
|
||
|
||
- `--force`: Ignores and overrides any dependency conflicts, forcing the
|
||
installation of packages.
|
||
- `--legacy-peer-deps`: Skips strict peer dependency checks, allowing
|
||
installation of packages with unmet peer dependencies to avoid errors.
|
||
|
||
</AccordionContent>
|
||
|
||
</AccordionItem>
|
||
</Accordion>
|
||
|
||
### Solution 2: Use React 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.
|
||
|
||
```bash
|
||
npm i react@18 react-dom@18
|
||
```
|
||
|
||
Whichever solution you choose, make sure you test your app thoroughly to ensure
|
||
there are no regressions.
|
||
|
||
## Using shadcn/ui on Next.js 15
|
||
|
||
### Using pnpm, bun, or yarn
|
||
|
||
Follow the instructions in the [installation guide](/docs/installation/next) to install shadcn/ui. No flags are needed.
|
||
|
||
### Using npm
|
||
|
||
When you run `npx shadcn@latest init -d`, you will be prompted to select an option to resolve the peer dependency issues.
|
||
|
||
```bash
|
||
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](https://www.npmjs.com/package/@radix-ui/react-icons) | ✅ | |
|
||
| [lucide-react](https://www.npmjs.com/package/lucide-react) | ✅ | |
|
||
| [class-variance-authority](https://www.npmjs.com/package/class-variance-authority) | ✅ | Does not list React 19 as a peer dependency. |
|
||
| [tailwindcss-animate](https://www.npmjs.com/package/tailwindcss-animate) | ✅ | Does not list React 19 as a peer dependency. |
|
||
| [embla-carousel-react](https://www.npmjs.com/package/embla-carousel-react) | ✅ | |
|
||
| [recharts](https://www.npmjs.com/package/recharts) | ✅ | See note [below](#recharts) |
|
||
| [react-hook-form](https://www.npmjs.com/package/react-hook-form) | ✅ | |
|
||
| [react-resizable-panels](https://www.npmjs.com/package/react-resizable-panels) | ✅ | |
|
||
| [sonner](https://www.npmjs.com/package/sonner) | ✅ | |
|
||
| [react-day-picker](https://www.npmjs.com/package/react-day-picker) | ✅ | Works with flag for npm. Work to upgrade to v9 in progress. |
|
||
| [input-otp](https://www.npmjs.com/package/input-otp) | ✅ | |
|
||
| [vaul](https://www.npmjs.com/package/vaul) | ✅ | |
|
||
| [@radix-ui/react-icons](https://www.npmjs.com/package/@radix-ui/react-icons) | 🚧 | See [PR #194](https://github.com/radix-ui/icons/pull/194) |
|
||
| [cmdk](https://www.npmjs.com/package/cmdk) | ✅ | |
|
||
|
||
If you have any questions, please [open an issue](https://github.com/shadcn/ui/issues) on GitHub.
|
||
|
||
## Recharts
|
||
|
||
To use recharts with React 19, you will need to override the `react-is` dependency.
|
||
|
||
<Steps>
|
||
|
||
<Step>Add the following to your `package.json`</Step>
|
||
|
||
```json title="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.
|
||
|
||
<Step>Run `npm install --legacy-peer-deps`</Step>
|
||
|
||
</Steps>
|