Unable to install major packages with Next.js 15 and React 19 RC

[igordanchenko]

Link to the code that reproduces this issue

https://stackblitz.com/edit/nextjs15-react-rc-peer-dep?file=README.md

To Reproduce

1. Open sample repro at https://stackblitz.com/edit/nextjs15-react-rc-peer-dep?file=README.md (or create a starter app with create-next-app)
2. Run npm i @mui/material or npm i react-hook-form in the console
3. Observe the following errors:

❯ npm i @mui/material
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: undefined@undefined
npm ERR! Found: react@19.0.0-rc-02c0e824-20241028
npm ERR! node_modules/react
npm ERR!   react@"19.0.0-rc-02c0e824-20241028" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0 || ^18.0.0 || ^19.0.0" from @mui/material@6.1.5
npm ERR! node_modules/@mui/material
npm ERR!   @mui/material@"*" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! 
npm ERR! For a full report see:
npm ERR! /home/.npm/_logs/2024-10-29T13_29_55_157Z-eresolve-report.txt

❯ npm i react-hook-form
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: undefined@undefined
npm ERR! Found: react@19.0.0-rc-02c0e824-20241028
npm ERR! node_modules/react
npm ERR!   react@"19.0.0-rc-02c0e824-20241028" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17 || ^18 || ^19" from react-hook-form@7.53.1
npm ERR! node_modules/react-hook-form
npm ERR!   react-hook-form@"*" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! 
npm ERR! For a full report see:
npm ERR! /home/.npm/_logs/2024-10-29T13_29_07_240Z-eresolve-report.txt

Current vs. Expected behavior

Unable to install major packages with Next.js 15 due to react RC peer dependency. npm install fails with the "Could not resolve dependency" error (see repro above).

For example, @mui/material uses the following React peer dependency range - ^17.0.0 || ^18.0.0 || ^19.0.0, which fails with the React RC version installed by default from Next.js 15 peer dependencies. The same issue happens with react-hook-form and ^16.8.0 || ^17 || ^18 || ^19 peer dependency range, and also other packages using >=18 peer dependency range.

I'm aware of the following workarounds, but it seems like a major inconvenience and really a blocker for inexperienced developers.

1) Install with --legacy-peer-deps flag:

npm i --legacy-peer-deps @mui/material

2) Add React version overrides to package.json:

"overrides": {
  "@mui/material": {
    "react": "19.0.0-rc-69d4b800-20241021",
    "react-dom": "19.0.0-rc-69d4b800-20241021"
  }
}

or

"overrides": {
  "react": "$react",
  "react-dom": "$react-dom"
}

3) Downgrade react to 18

Provide environment information

Operating System:
  Platform: darwin
  Arch: x64
  Version: Darwin Kernel Version 24.0.0: Tue Sep 24 23:36:30 PDT 2024; root:xnu-11215.1.12~1/RELEASE_X86_64
  Available memory (MB): 32768
  Available CPU cores: 12
Binaries:
  Node: 22.10.0
  npm: 10.9.0
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 15.0.1 // Latest available version is detected (15.0.1).
  eslint-config-next: 15.0.1
  react: 19.0.0-rc-69d4b800-20241021
  react-dom: 19.0.0-rc-69d4b800-20241021
  typescript: 5.6.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Not sure

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local), next start (local)

Additional context

I've also tested with the latest canary (15.0.2-canary.10) and observed the same issue.

[dualdetail]

Just downgrade react to version 19 or 18. React isn't bundled into nextjs it's just a version number set in the package that npx create-next-app generates.

[igordanchenko]

Thank you for the suggestion (though I'm not sure what you mean by downgrading react to 19, as 19 stable hasn't been released yet)

Yet the issue manifests itself out of the box with a brand new starter app created with the create-next-app, and that's what this ticket is about.

p.s. To make it clearer, I've updated the issue description to avoid the word "bundled"

[dualdetail]

My bad, missed that. So you want it to work with latest react? Mui would have to update it's deps as nextjs is compatible with the react version you have.

[igordanchenko]

My bad, missed that. So you want it to work with latest react?

Correct, since React 19 RC is officially supported in Next.js 15. Downgrading to React 18 would prevent developers from ensuring compatibility with the upcoming React 19 GA.

Mui would have to update it's deps as nextjs is compatible with the react version you have.

This issue is not limited to MUI. I mentioned react-hook-form in the description as another prominent example. 3rd-party libraries with peer dependencies ^19 or >=18 won't install out of the box, and that's what this ticket highlights as an issue. The other workarounds I mentioned in the description are not entirely user friendly.

[igordanchenko]

I'm just curious why Next.js team didn't add the following override to the create-next-app template?

"overrides": {
  "react": "$react",
  "react-dom": "$react-dom"
}

Is there any downside to doing that?

[na-zi-ya]

did my suggestion work for you..??