How to Upgrade Strapi 4 Project to Strapi 5? - A Guide by Experts

If you are one of the over 10 million people who use Strapi to power their project, we’ve got some good news: Strapi 5 is live! 

While Strapi has already left WordPress behind in the headless CMS race, it is about to go even further with its V5 update.

With exciting new features and powerful upgrades, Strapi has finally released a stable version of its much-awaited update to its users. 

So, if you’ve been wondering how to upgrade Strapi 4 to 5, we’ve got you covered! 

In this Strapi migration guide, we’ll tell you all about the new features of the latest Strapi version and the main differences between Strapi 4 and Strapi 5. 

We’ll also tell you how to upgrade Strapi 4 projects to Strapi 5 in a seamless and phased-out manner. 

Before we move forward, we must mention that Strapi V4 will be supported till 2026. So, while you have plenty of time to upgrade to V5, you know what they say about the early bird! It gets all the worms (or, in this case, all the advantages!).

Ready to harness the power of the next generation of headless Strapi? 

Let’s get started!

Strapi 5 Features - What’s New? 

According to Strapi, version 5 is all set to lead its users into a new dimension of content publishing and maintenance. The upgrade is packed with tons of features designed to improve user experience and development pace.

Strapi claims that the new version increases development speed by 15% and is also 15% lighter than Strapi 4. Here are some of the most noteworthy improvements you’ll notice: 

Improved Draft and Publish

The new draft and publish function is designed to reduce errors in the content you create. It allows you to publish and save your content simultaneously. However, it also allows you to separate the draft and the published content through different tabs. 

Additionally, you can also seamlessly publish changes you make to the content, thereby enabling smoother collaboration between developers and creators. 

Content History

Strapi’s attempt at creating a content time machine isn’t too bad! The new version allows you to easily revert back to an earlier version of your content. So, if you face problems with the new version of your pages, you can simply buy more time to deal with the changes by reverting to a more stable version of it. 

Here, Strapi aims to protect your website against data loss, sub-optimal edits and unnecessary disruption. 

You May Also Like: Future Programming Languages 2050

Strapi, Powered by TypeScript

Strapi 5 boasts TypeScript support and integration. This ensures that developers face fewer bugs and greater type safety. Get ready for a smoother collaborative experience! 

The new Strapi also includes an improved admin panel and an even friendlier user interface for customization and integration. 

New Plug-Ins, New APIs

The new Strapi also features more intuitive plug-in creation, so integrating microservices has never been easier. Strapi has further sharpened its support for GraphQL API integration capabilities. 

It now functions with reduced payload sizes for efficient data transmission and allows for more detailed sorting and pagination, leading to more efficient and sophisticated queries. 

Tag, You’re It!

Lastly, Strapi has introduced a new feature called “Tagging,” which allows you to index similar pages with a tag. You can access the index by clicking on the tag, which leads users to the index page. 

So, Strapi allows you to create a cluster of pages with similar content, information or styles. 

Thus, Strapi 5 features represent a comprehensive overhaul of the headless platform’s capabilities, rendering it even more powerful content delivery system. 

The Upgrade: What to Keep in Mind Before Updating to V5

Before we get into how to upgrade Strapi projects to V5, let’s understand how a few preliminary steps can ensure that the process goes as smoothly as possible.

1. Back-Up Your Database 

The first thing you want to do to prepare for the update is back up your existing database.

Strapi is powered by the SQLite Database. So, if you’re using the default database, your database file will be named data.db. You can find it in the .tmp/ folder at the root of the Strapi app. 

If you’re using any other databases, visit the official Strapi documentation of MySQL and PostgreSQL on their dedicated pages. 

Lastly, if you’re hosting your project on Strapi Cloud, here’s the page that will help you manually back up your database. 

2. Codemods will Help You

Another thing you must know about before updating is Codemods. Codemods are automated tools designed to help you with large-scale modifications. They are especially useful for: 

• Code refactoring,

• Adapting to API changes, and

• Applying coding style updates. 

Codemods will help you make several important changes to your source code. They will make automatic changes to the app codebase in accordance with the breaking changes introduced before the latest version. 

3. Discover the Breaking Changes

It is important to understand exactly what has changed with Strapi 5. The breaking changes page will tell you about the most important changes. Strapi has categorized the breaking changes according to six different types: 

• Changes to the Database, 

• Changes to the Dependencies,

• Changes to the Configuration, 

• Changes to Strapi Objects, Methods, Packages and Back-end Customization, 

• Changes to Plug-ins, Providers and Admin-Panel Customization, and

• Changes to the Content API. 

The page mentioned above will tell you whether the changes will affect API integration and whether the changes are handled automatically by the Codemods. 

To see the full list of codemods, run the following command in your terminal: npx @strapi/upgrade codemods ls. Alternatively, you can visit the GitHub Repository to view the full list of changes. 

4. Update to the Latest Minor Version and Patch of Strapi 4

Before you can update to V5 of Strapi, you must ensure that your project is updated to the latest minor version and patch of Strapi 4. 

Here’s how the semantic naming convention of Strapi works: 

• The first number (4) refers to the major version number,

• The second number (25) refers to the minor version number,

• The third number refers to the patch version number. 

You can use the Codemod tools to upgrade your existing project to Strapi V4.25.9. Here’s how you can update to the latest pre-V5 version of Strapi:

• Run the code <npx @strapi/upgrade major> to update the latest major version, 

• Run the code <npx @strapi/upgrade minor> to update to the latest minor version, 

• Run the code <npx @strapi/upgrade patch> to update to the latest patch version. 

Alternatively, you can run the utility function that allows you to select which Codemods will be executed to update your Strapi version. Here’s how to use the codes: 

• To view a list of the available Codemods, run the code <npx @strapi/upgrade codemods ls>

• To select specific Codemods, run the code <npx @strapi/upgrade codemods run>

• To run only a particular Codemod, use the code <npx @strapi/upgrade codemods run 5.0.0-strapi-codemod-uid>
  

If you run into trouble at any point, use the function <--help>. It will display useful information to help you troubleshoot problems with the upgrade. 

Now we’re all set to understand how to upgrade Strapi 4 to 5 in a phased manner! 

Step-by-Step Upgrades Process

Once you have followed the steps listed above, you’re finally ready to update to Strapi V5. Here’s how to upgrade Strapi to V5 in a step-by-step process and experience its latest features and functions. 

1. Prepare for the Upgrade

Once again, before beginning the upgrade process, ensure that you’ve: 

Backed up your database 

Use the process listed above to ensure that your database is safely backed up. This will eliminate the risk of data loss in case the migration goes wrong. 

Backed up your code

If your code is git-versioned, you will have to create a new dedicated branch in order to run the migration. If your code is not gir-versioned, you must create a backup of the working V4 code and store it safely. 

Checked the Plugin Compatibility

This is very important as some plugins may not be compatible with V5. This might impair functionality, upset the microservice infrastructure and upset several users. 

To avoid this, make a list of the plug-ins you are deploying. Visit the marketplace page and check their documentation to verify their compatibility with Strapi Version 5. 

2. Run the Automated Migrations with the Upgrades Tool

Run the automatic upgrade tool. This function will execute the official update. This means, it will install the dependencies of Strapi V5 and run the Codemods that handle several breaking changes. 

As mentioned, here’s the code you need to run to execute the update: <npx @strapi/upgrade major>

After running the automated tool, check to see if you need to manually update some of the code. This will be mentioned by the Codemode function via the <__TODO__> function. 

Several of the pending changes might be due to the shift from the Entity Service API to the new Document Service API. Visit the dedicated breaking changes page to see what’s changed. 

3. Manual Upgrades

The update process will largely affect three parts of your application: database migration, configuration and admin panel customization. 

Go to the dedicated breaking changes page to see if manual actions are necessary after the upgrades tool has finished running. Here are some changes that may be required: 

Database Migration

• Strapi V5 does not support MySQL v5. 

• V5 only supports better-sqlite3. 

• V5 only supports mysql2.

• V5 triggers lifecycle hooks differently. 

Configuration

• V5 handles some environment variables by the server configuration.

• V5 requires custom configuration to meet specific requirements. Check out the full list here to ensure that your project meets these requirements. 

• Admin Panel Configuration

The only major change in the admin panel configuration is that the helper plugin has been removed. Check this page for detailed information about the changes pertaining to the helper plugin. 

4. Migrate the APIs 

As we have seen, Strapi has made major changes to its API ecosystem for a smoother user experience. This includes both, RESTful and GraphQL APIs. 

The retro-compatibility functionality will help you upgrade to the new APIs. It will ensure that your V4 plugin temporarily runs with V5 before you can update it to the requirements of the latest version. 

Here’s how you can use the retro-compatibility functionality and guided migration to adopt a phased-approach to harness Strapi 5 benefits for your project: 

RESTful APIs 

1. First, enable the retro-compatibility flag by setting <Strapi-Response-Format: v4> as your header. 

2. Next, check the dedicated change entry page for REST APIs. Only update the mutations and queries of your REST APIs. 

3. Third, verify that your client-side operation is showing desirable and appropriate responses to user queries. 

4. After verification, remove the <Strapi-Response-Format: v4> to disable the retro-compatibility flag. 

Now, you can safely start using your new response format! 

GraphQL APIs 

1. Set the <v4CompatibilityMode> to <true> to enable the retro-compatibility mode. You can find this in the <graphl.config> object in the </config/plugins.js|ts> file. 

2. Go to the breaking change entry page for GraphQL APIs and follow the guide to update only the queries and mutations parts of the APIs. 

3. Next, check whether the client-facing part of the website is issuing the correct responses to user queries. 

4. Once you have validated the responses, switch the <v4CompatibilityMode> to <true> to disable the retro-compatibility functionality. 

And that’s it! You’ve successfully started using the new and improved version of Strapi! 

Facing Trouble Updating to V5? Green Apex Can Help…

Pivoting to Strapi V5 is definitely desirable because of the groundbreaking changes it has introduced to make the development quicker and the user experience smoother.

But, here’s the thing: if you’re from a non-technical background and simply want Strapi 5 benefits, you might find the upgrade tough to deal with. 

But don’t worry! That’s exactly where we come in! Our Strapi CMS Development experts can help you develop a phased approach to migrating to Strapi 5. We will provide you with complete migration support so you can take advantage of Strapi 5 features like quick content creation and smooth delivery. 

Our experience in handling diverse Strapi projects means you never have to worry about downtime, update errors or post-deployment maintenance. 

We will diligently help you follow every step listed here in this Strapi 5 migration guide to ensure that your Strapi project is upgraded within no time! 

Reach out to us to speak about your Strapi project or learn more about our end-to-end Headless CMS Development services. 

Collaborate with us and let us take your Strapi project to the next level!