In-Depth Explanation of React Version Handling Doc

[abhishekmardiya]

There have been multiple discussions and some confusion around React version handling in Next.js. This PR adds an in-depth explanation to clarify how React and react-dom versions are managed internally, and why they still need to be declared in package.json.

The goal is to help developers better understand this behavior and reduce recurring questions around it.

Reference discussion:
#87958

@icyJoseph

[icyJoseph]

This is a tricky one.

Right now the docs already instruct users to install react and react-dom during manual setup, without making that conditional (implicitly made w/ create-next-app). We also call out, both in the installation flow and in the React version handling docs, that the App Router uses the React canary channel internally.

We already explain what needs to be installed and which React version is actually used in App Router.

We added a more prominent note about this in the docs a few months ago (rather recently in terms of App Router lifetime), so much of the confusion being referenced likely predates the current guidance.

The question for me is whether this change helps prevent users from doing something incorrectly, or whether it reflects a concrete issue we are seeing in practice. Right now it reads more like additional background than something that changes user behavior.

That said, if there are specific examples of users misreading the current docs or taking incorrect action as a result, I think it would make sense to iterate with that in mind. For the CVEs, the place to follow guidance from are the Security Advisories published, not the installation page.

I think the PR diff could also be a lot shorter, and I do wonder if the next CLI API reference is a better place for a note on this topic. Still not as long as presented here.

[abhishekmardiya]

Thank you for the acknowledgment — I understand that this change may feel overly verbose. I’m happy to shorten the diff and reduce this to a brief note. I can also move it to the Next CLI docs if that’s a better fit and better supports developers, rather than causing confusion.