Blog title

Step 1: Understand How V3 and V4 Differ

Understanding how v4 differs from v3 is essential before beginning the migration. Among the significant modifications are:

• New Codebase Structure: Strapi v4 makes it easier to maintain and modular by introducing a new folder structure.
• API Improvements: v4 makes use of OpenAPI specifications and endpoints are now more standardized.
• Database Migration: v4 requires schema and data updates and handles database migrations differently.

Common Challenge: If you have a highly customized Strapi v3 instance, it may be challenging to understand these changes.
Solution: Plan to migrate each one individually after reading the official upgrade guide and noting your current v3 customization. Don’t tamper with everything.

Step 2: Get Your Current Project Ready

Prior to initiating the migration:

• Make a full backup of your Strapi v3 project, including the uploaded files and database.

Challenge: If you use cloud storage for your assets, backing up large projects may take some time.
Solution: You can create a local store backup.zip or Create a distinct branch specifically for backup in the event of version control (Git).

• Audit Custom Code: List every modification made to your Strapi v3 instance, including unique plugins, configurations, and APIs.

Problem: If there is not enough documentation for your modifications.
Solution: Reverse-engineering them can help you resolve your complexity, but remember to keep a fresh document with your migration modifications. Your fellow developers will find this to be very convenient.

• Copy Configuration Details: Transfer your existing configurations (e.g., .env details) to ensure a smoother transition to v4.

Step 3: Create a New Strapi v4 Instance

Upgrading from version 3 to version 4 is not possible. Rather, you must start a new Strapi v4 project:

npx create-strapi-app@latest my-project --quickstart

• Database Type: To make data migration easier, select the same database type as your v3 project (e.g., MySQL, PostgreSQL, etc.).

Challenge: Changing database types (such as MySQL to SQLite) might necessitate the use of extra data transformation tools.
Suggestion: My recommendation is that you stick with your old database and perform a database-specific migration separately.

yourFirsLookOfStapi

After the successful completion of setup you will see the above interface on your browser.

Step 4: Recreate Components and Collections

Although Strapi v4 offers a new method for handling different kinds of content, you can still transfer your current collection and components straight from the old code base to the new one.

• Copy Collection’s: Simply navigate to your v3 codebase’s /api directory, copy each collection, and then paste it in the appropriate location in your v4 codebase
• Copy components: To get your old components in new ones, repeat the process from the /components directory after you’ve finished with collections.
• Migrate Relations: Because the syntax has changed in version 4, pay attention to the relationships between collections.

Challenge: Manually mapping intricate relationships can be prone to mistakes. Throughout the process, keep track of fields and relationships using a spreadsheet.
Tip: To make your new v4 structure more efficient, eliminate extra code or superfluous data attributes.

folder of api and components of your strapi

Step 5: Data Migration

One of the most challenging aspects of the upgrade is data migration. There are two primary methods:

• Export and Import Data:
  • All you have to do to carry out database migration is execute a script in accordance with the instructions, and your converted data for Strapi v4 will be ready.
    • Script Link: https://github.com/strapi/migration-scripts
  • For backup purposes, export your data from the v3 database using a program like mysqldump or pg_dump.
• Flatten API’s responses:
  • • This section of Strapi v4 is entirely different if you’re using GraphQL in your existing Strapi.
  

  Query comparsion of graphQL in strapi v3 and v4

  • The response format has been updated for both GraphQL and the RESTful API in accordance with the GraphQL query style update. You can then use this plugin to change the data to your old notation in order to solve this issue.

  Plugin Link –  https://market.strapi.io/plugins/strapi-plugin-untransform-response

  Challenge: Ensuring data consistency during migration can be tricky, especially for large datasets with complex relationships.
  New Consideration: Strapi v4 enforces a default page limit of 10. Update your queries or configurations if you need to fetch larger datasets

Step 6: Modify Permissions and APIs

V4 APIs use a different format, and v3 custom endpoints may not work. To correct this:

• Recreate Custom Endpoints: Use the new Strapi v4 format to rewrite your custom controllers and services.
• Update Permissions: In the v4 admin panel, change the permissions for the roles.

Step 7: Plugin Migration

Strapi v4 is incompatible with plugins made for Strapi v3. You must:

• Verify the availability of the plugin: **Official v4 versions are available for some well-known v3 plugins, such as Upload and GraphQL. Use the CLI to install them:
  • npm install @strapi/plugin-graphql
• Rewrite Custom Plugins: Use the new v4 architecture to refactor any custom plugins you have created.

Note: Deeper queries are supported by GraphQL in version 4. Try out its new features to get the most out of your API interactions.

Step 8: Test Thoroughly

After everything is configured, test your v4 instance in all respects:

• Content Management: Make sure you have the ability to add, edit, and remove content.
• API Responses: Use Postman or similar tools to validate all API endpoints.
• User Permissions: Check permissions and access based on roles.

Tip: Look for differences between v3 and v4 by comparing the data fetching and response structures.

Step 9: Deploy the New Instance

Finally, set up your Strapi v4 instance in the hosting environment of your choice. Prior to going live:

• Update DNS Records: Point the new server to your domain.
• Test in Production: To identify any problems unique to a deployment, conduct a dry run in the production setting.

Challenge: Users may be impacted by switch outages; schedule a maintenance window.

Step 10: Cleaning Up After Migration

Following a successful migration:

• Update Documentation: For future use, record your new architecture and procedures.

Conclusion

Strapi v3 to v4 migration is a multi-step procedure that needs to be carefully planned and carried out. A more reliable, maintainable, and effective CMS is the end result, despite the considerable challenges—which range from schema modifications to API refactoring. Don’t be afraid to ask for assistance from the  Strapi community and proceed with the migration in small steps. I hope your journey of migration goes well!