[Bug]: Migration guide in v4 is missing a breaking change

[icefo]

Link to the documentation page or resource

https://docs-v4.strapi.io/dev-docs/migration-guides

Describe the bug

I had a really old version of strapi v4 that I upgraded, following the migration guides up to the latest 4.15.5. Things went well and since there was no migration notes since 4.15.5, I went straight to 4.25.22. Yarn install worked but yarn build failed because react is now an explicit dependency.

I found this thread on the strapi forums and the solution there worked (merge the packages.json of a new strapi installation with mine).

I also wonder if the migration guides should use the ~ (eg "~4.15.5" instead of "4.15.5") to get the latest patch instead of the exact version. I did that and it went fine but there may be gotchas I don't know.

Do you also know why react became an explicit dependency ? It seems it's going to complicate future upgrades too.

Additional context

No response

Suggested improvements or fixes

Here is the naive upgrade of the dependencies:

"dependencies": {
"@strapi/strapi": "~4.25.22",
"@strapi/plugin-users-permissions": "~4.25.22",
"@strapi/plugin-i18n": "~4.25.22",
"pg": "^8.16.3",
"strapi-plugin-populate-deep": "^3.0.0"
},

Here is the correct one:

"dependencies": {
"@strapi/strapi": "~4.25.22",
"@strapi/plugin-users-permissions": "~4.25.22",
"@strapi/plugin-i18n": "~4.25.22",
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-router-dom": "5.3.4",
"styled-components": "5.3.3",
"pg": "^8.16.3",
"strapi-plugin-populate-deep": "^3.0.0"
},

I'm also using postgres and a plugin but they are not part of the problem.

Related issue(s)/PR(s)

No response

[github-actions]

🤖 I've analyzed your question and here's what I found:

Hi there! Thank you so much for taking the time to share your experience and for providing such a detailed report—your feedback is incredibly valuable to us and to the wider Strapi community. We really appreciate your effort in helping improve the migration experience for everyone.

About the Missing Migration Note

You’re absolutely right that the need to explicitly add react, react-dom, react-router-dom, and styled-components as dependencies in your project can be a confusing hurdle, especially when upgrading from older Strapi v4 versions. This requirement is not always clearly highlighted in the migration guides for v4, and your suggestion to clarify this in the documentation is spot on.

Why did this change happen?
In more recent Strapi v4 releases, the project moved away from aliasing these dependencies internally. Now, Strapi expects them to be present in your project’s package.json directly. This change was made to improve compatibility and reduce dependency conflicts, especially as the ecosystem evolves and plugins may require different versions of these libraries. However, it does mean that manual intervention is needed during upgrades, as you discovered. This is also documented as a breaking change for Strapi 5, but the same principle applies to late v4.x versions as well (see breaking change for webpack aliases removal).

Recommended Dependency List

For anyone upgrading to the latest v4.x, your corrected dependencies block is a great reference:

"dependencies": {
  "@strapi/strapi": "~4.25.22",
  "@strapi/plugin-users-permissions": "~4.25.22",
  "@strapi/plugin-i18n": "~4.25.22",
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "react-router-dom": "5.3.4",
  "styled-components": "5.3.3",
  "pg": "^8.16.3",
  "strapi-plugin-populate-deep": "^3.0.0"
}

If you’re missing any of these, you may encounter build errors like Cannot find module 'react'.

About Using ~ in Version Numbers

Your suggestion to use ~ (tilde) in version numbers is a good one. This allows you to automatically get the latest patch updates within the same minor version, which can help avoid missing important bug fixes. However, always review the Strapi upgrade tool and release notes to ensure compatibility, especially when skipping multiple versions.

Next Steps & Suggestions

• Documentation Improvement: Your feedback highlights a real gap in the migration guides. We’ll flag this for the documentation team to ensure future users are aware of the explicit dependency requirement.
• Feature Requests: If you’d like to see this process improved or automated, please consider submitting your suggestion to Strapi Feedback.
• Further Help: For more complex upgrade scenarios or if you run into other issues, the Strapi Discord and community forums are great places to get real-time help.

If you believe this is a product bug or a core functionality issue rather than just a documentation gap, please let us know and we can tag @pwizla to consider moving this to the main Strapi repository.

Thanks again for your thoughtful report and for being part of the Strapi community! If you have any more questions or suggestions, feel free to ask.

📚 Relevant documentation:

• Frequently Asked Questions - How to fix the build error Error: Cannot find module @strapi/XXX
• Internationalization (i18n) is now part of the strapi core
• Plugins upgrade summary
• Release notes - New content
• Step-by-step guide to upgrade to Strapi 5 - Step 2: Run automated migrations
• Strapi factories import have been updated
• Strapi users react-router-dom v6
• Strapi v4 to Strapi 5 breaking changes
• Strapi v4 to Strapi 5 breaking changes - Strapi objects, methods, packages, and back-end customization
• The CLI default package manager is not yarn anymore
• The Strapi Design System has been upgraded to v2
• Upgrade tool
• Upgrade tool - Upgrade to a new version
• Upgrading to Strapi 5: Introduction and FAQ
• Webpack Aliases are removed

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.