Preparation
- Backup Everything: We started with comprehensive backups of our project and database. No room for error here.
- Study the Docs: We dove into the Strapi v5 documentation to get a handle on new features and potential breaking changes.
Migration Steps
- Initialize Strapi v5: We set up a fresh Strapi v5 project:
- npx create-strapi-app my-project --quickstart
- Database Setup: Configured the database in config/database.js to match our current setup.
- Data Migration: Exported data from the old project and imported it into the new Strapi v5 instance using scripts.
- Rebuild Content Types: Manually recreated content types and reinstalled necessary plugins, checking for v5 compatibility.
- Code Refactor: Updated our custom code for compatibility with Strapi v5’s API and addressed any deprecated features.
Testing
- Local Tests: Ran the project locally to catch issues early.
- Staging Deployment: Deployed to a staging environment identical to production to identify environment-specific bugs.
Go Live
- Prep Production: Ensured the production environment was ready for Strapi v5.
- Deploy: Deployed to production and closely monitored the project.
- Verify: Checked data integrity and overall functionality post-deployment.
Lessons Learned
- Simpler Migration: The migration to v5 was smoother compared to the jump from v3 to v4, thanks to better automation by the Strapi team.
- Mono-repo Issues: Running Strapi v5 in a mono-repo setup can be problematic.
- Plugin Compatibility: Many third-party plugins are not yet compatible with v5.
- Import Handling: Adjust imports due to changes in Strapi v5’s export methods and address TypeScript issues.
- Automated Database Migration: This worked well, but note that table names are now shortened (e.g., “components” to “cmps”).
- User Permissions Bug: In @strapi/plugin-users-permissions 5.0.0-beta.7, we encountered bugs with field visibility and editing as a super admin.
- Backend Customization: Migrating backend code, especially lifecycle hooks and EntityService API usage, was necessary. We found that lifecycle hooks are triggered differently, and the afterUpdate lifecycle didn’t trigger as expected in beta.
- Frontend Adjustments: Our frontend needed tweaks to handle the new flattened API responses, requiring a document ID in requests.
- Upgrade Tool Limitations: The Strapi upgrade tool didn’t work for us, necessitating a manual migration.
Conclusion
- Migrating to Strapi v5 was worth the effort for the performance and feature enhancements. By thoroughly preparing and testing, we minimized downtime and ensured a smooth transition. If you're planning a similar upgrade, keep these lessons in mind for a streamlined migration process.
- Got a question? Shoot us an email to sales@notum-tech.ch
