Strapi 3x to 4x migration
Straipi headless CMS has progressed very well over the time and Strapi version 4 takes a leap by redefining the way headless CMS are developed.
The latest version of strapi 3.x is a progressive development and has quite few things that needed redoing in a better. Strapi4 is a complete rethink and rectifies the legacy issues with core structures and definition models defined by strapi3.
Since Strapi 4 is quite a big bone by design and structure migration from 3.x to 4.x could be a complicated depending on your current strapi 3 implementations. in short, the upgrade from strapi three to four potentially is lot of work on database, strapi implementation and even on the connected front ends.
There is change in structure of database, rest and GraphQL API’s, server-side API layers, models specially their relations, where everything from data models, routes, policies, lifecycle events, controllers as all have changed quite drastically.
The Upgrade requires conversion in almost every area of the implementation that is schema definitions within API, components, and extensions along with their lifecycle event handlers. Custom routes conversion to either old style routes or new modern.
Automated Strapi Migration (published on GitHub).
As for as the strapi (not the front end) upgrades are concerned we have developed an automated migrations script that migrates over 80 percent of the strapi customization and database reliably this includes complete content type schemas, controllers, services, routes, policies, lifecycles with very reasonable accuracy.
The script also generates MySQL database migration scripts for strapi 3x to strapi 4.1.x versions.
the script is published at git hub with name strapi3to4migration at https://github.com/eharain/strapi3to4migration
please download, correct the directories, in index.js, install fresh instance
of strapi4 and run migration script it will generate the necessary files in new
instance of strapi 4 , open the snapshot directory and run the MYSAL migration
script and your migration is done. double check the migrated code files
specially the js files and you are all done.
readme is here https://github.com/eharain/strapi3to4migration/tree/master#readme
Please do reach us if you need any help or advice.
Key technical differences in strapi 3 and 4 structures.
The Directory Structure
The directory structure of the strapi 4 is quite changed from previous one. The extensions, plugin, components and api directories are moved under source directory called src.
The api entity directory structure has also changed, this includes the naming as well
The schema files are now moved deeper under content types and lifecycle events are declared in lifecycle JavaScript file. The routes are now split between custom routes and core routes the custom routes are quite similar to routes json file.
Schema definitions
Strapi 4 Schema definitions have changed significantly as compared to strapi 3.
The biggest impact is on relations where new relations declaration is much more sensible and defines it quite clearly what kind of relation it is as compared to earlier definitions.
Schema info
Unlike strapi 2 the info element in strapi 4 has name replaced with singular, plural and display names making the naming quite clear
Private attribute for a property.
In strapi 4 the attributes are now marked private under options in a list not as property of the actual attribute
Relations definition
In strapi 4 the relations are now marked as one to one and many term that makes it very readable and clear while in strapi 3 this model property was indicating one and collection was indicating many sides of the relation. Similarly, via and dominant property was indicating the bidirectional relations where in strapi 4 this is now clearer with mapped by and inversed by properties.
the model and collection are replaced with new attribute target the relations is indicated by clear relation types.
the target names are prefixed with namespace that API, plugin and admin with group and model names.
Files and media
There are changes in model file to media plugin relation as reference.
Model Components
The components names are now prefixed with their group names and their actual definition stays quite consistent to entity schemas.
Routes
The routes are now split between custom routes and core routes the custom routes are quite similar to routes json file of strapi 3 except it now is In JavaScript object format and exported as a module.
Services, Controllers and Policies are similar except with context changes and the object references so would require code reviews and testing for their implementations. the lifecycle also has minor variations that will need code review and in some cases re writes.
The configurations and plugin configurations also have changes along with the overall strapi modules and plugins moved to @strapi directory and will require appropriate changes.
Migrating the entities to strapi version 4
Due to the amount of difference between versions the migration approach we have adapted it by installing a fresh instance of strapi 4 instance. We have generated a script that will iterate the entries under api, components and extension directories under strapi 3 installation and generate new schema files in strapi 4 under its new format and naming convention. These schema definition and routes are converted quite reliably the other code files will need visual inspection; we will publish our finding as we go through this process bit more in detail.
Moving the Data from strapi v3 to strapi v4 database.
There are two separate approaches that can be taken to migrate the data the fastest of these is moving data within database engines with necessary transformation and the other approach is to request data from strapi 3 api and submit it to strapi 4 instance and both the approaches have some pros and cons. For the migrations we have performed so far, we have adapted the approach of moving data across databases
truncate strapi 4 eneity tables in order
1. truncated entity component tables and link tables as well as fire morphs and in the end entity tables.
TRUNCATE TABLE strapi4.`companies_claims_links`;
then insert into entity tables,
Changes in server-side API
Changes in client API
The standard api response and request has new element data, attributes and meta so you will have to adjust your requests and response utilization accordingly in many places.
there are few standard api including counts removed against each entity so be ready to adjust your front ends.
How we can help with the migration to strapi 4.
Thanks to our strapi developers Our free automation script can save you time on strapi migration and will cover 80 percent of the efforts that you will otherwise have to do with manual steps involved.
This includes strapi server code upgrade and generating database migration scripts aiming MySQL, MariaDB and postgresql. please note at the time of righting this mongodb is not supported in strapi 4. The link of the script is give above.
You still need to perform your front upgrades and look into custom codes and modifying some of the custom codes to new back end apis etc etc so its quite a pain. We can offer you this as a service and can provide you with fast turnaround as we by now have gone through this few times. Please do not hesitate to contact us we can be helpful even if it’s of an advisory nature.