Strapi 5 is officially available this week!! Upgrading from Strapi 4 to Strapi 5 was a challenging process, but it was absolutely worth it. In this post, I'll guide you through my experience, the roadblocks I encountered, and how I finally managed to get everything working.
Why Upgrade to Strapi 5?
Strapi 4 had some serious limitations that made managing content a bit of a nightmare.
It was slow, especially when working with the media library, and mobile support was almost non-existent.
Strapi 5, on the other hand, offers a much better experience with performance optimizations, a more responsive UI, and robust new features like Draft & Publish and Content History.
1. Performance and Stability Improvements
Strapi 4 often felt unresponsive, especially for larger projects. Strapi 5 brings substantial performance improvements, making the CMS more reliable and efficient.
2. Improved Content Management: A Lifesaver for Bloggers
Draft & Publish: This feature is invaluable for me as a blogger. It allows you to work on drafts without risking accidental publication.
You can save your progress and only publish when you're absolutely ready.
Content History: This acts like a version control system for your content, letting you restore previous versions whenever needed. It’s perfect for fixing mistakes or just looking back at your edits.
Preparing for the Strapi 5 Upgrade
Before jumping into the upgrade process, it’s essential to back up your data and ensure your plugins are compatible with Strapi 5. Here’s how I prepared:
- Export your database and make a copy of your project files. This step is crucial in case anything goes wrong during the upgrade process.
- Not all plugins are compatible with Strapi 5 yet. I had to keep some plugins on their older versions temporarily until they’re updated.
Step 1: Upgrading to Strapi 4
You can’t jump directly from Strapi 4 to 5, the first step is upgrading to Strapi 4:
Uninstall the Global Strapi Version
This was necessary to avoid conflicts between global and local installations.
npm uninstall -g strapiRemove and Reinstall Dependencies
I deleted the node_modules folder and package-lock.json file to clear out any old dependencies that might be causing issues. Then, I reinstalled all the project dependencies with the correct versions:
rm -rf node_modules package-lock.json
npm installInstall Strapi 4 Locally
I installed the latest version of Strapi 4 within my project directory. For most cases, you can use the following command:
npm install @strapi/strapi@4.25.12However, if you’re upgrading from a previous version, you might want to use the Strapi upgrade tool with the following command to handle the migration smoothly:
npx @strapi/upgrade major This tool can help automate the upgrade process, ensuring that your dependencies and configurations are correctly updated without manually uninstalling and reinstalling packages.
The only thing with this plugin is that you cannot jump directly from 4.24.4 to 5.0.0. Major upgrades require you to be on the latest version of Strapi 4 first. If you encounter an error like:
“Requirement failed: Doing a major upgrade requires to be on the latest v4 version, but found 14 versions between the current one and 5.0.0: 4.25.0, 4.25.1, 4.25.2, 4.25.3, 4.25.4, 4.25.5, 4.25.6, 4.25.7...”
Make sure to update to the latest Strapi 4 version first:
npm install @strapi/strapi@4.25.12This is required to have the latest major version before moving on to Strapi 5.
Update Your Plugins
I updated the plugins to versions compatible with Strapi 4 in my package.json. I noticed that the styled-components and react-router-dom versions were causing issues, so I made sure to align them with the necessary versions:
To fix this, I updated them to the required versions:
npm install react-router-dom@6 styled-components@6.1.13
Also;
{
"@strapi/plugin-users-permissions": "^4.25.4",
"@strapi/plugin-upload": "^4.25.4"
}Then ran:
npm run develop
Step 2: Upgrading to Strapi 5
Now that Strapi 4 was running smoothly, I moved on to Strapi 5. I kept the older plugin versions while updating Strapi and plugins that were compatible with Strapi 5:
I updated the core Strapi and the compatible plugins, while keeping the others on older versions:
{
"@strapi/strapi": "^5.0.1",
"@strapi/plugin-cloud": "^5.0.0",
"@strapi/plugin-i18n": "4.25.4",
"@strapi/plugin-upload": "^4.25.4",
"@strapi/plugin-users-permissions": "4.25.4"
}Run Strapi 5 Locally
Tested the application thoroughly to ensure everything was working as expected.
npm run develop
Step 3: Handling Strapi Cloud
If you’re using Strapi Cloud, you may notice that upgrading locally doesn’t automatically reflect on your cloud environment. Here’s what I did:
- I contacted Strapi Cloud support to make sure my cloud instance was updated safely.
- I avoided making changes to my cloud instance until I had a clear plan, especially since my local environment looked different from my cloud setup.
Conclusion
Strapi 5 offers a much more robust and efficient CMS experience, and while it took some effort to get there, the improvements in performance and usability are well worth it.
Thank you for reading!
Naz
