Still on Strapi v4? Planning the move to v5

A good share of the self-hosted Strapi installs we look at are still on v4. That made sense while v5 was settling down. Now it means running a major version that receives less attention every month, with plugins steadily dropping v4 support.

Moving from v4 to v5 is a real upgrade, not a version bump. The good news is that the work is predictable once it's properly scoped.

What changes

• A flattened REST response format: attributes are no longer nested under data.attributes
• Documents identified by a string documentId rather than a numeric id
• The Entity Service replaced by the Document Service, with draft and published versions handled as one document
• Plugin APIs updated, so custom and community plugins need checking or porting

The front end is the real work

Strapi provides codemods for the backend, and they handle a lot of it. The bigger effort is usually in the consuming applications. Every Next.js page, mobile app or integration that reads data.attributes or stores numeric ids needs updating. If several front ends share one Strapi instance, they all have to move together, or you need a compatibility layer while they move.

How we scope it

• Inventory every consumer of the API, including the ones nobody remembers building
• Check each custom and community plugin for a v5-compatible release
• Run the upgrade tool and codemods against a copy of the project and database
• Use the v4 compatibility response header during the transition so front ends can migrate one at a time
• Rehearse the database migration on a production-sized copy before the real cutover