How QBurst Migrated a Luxury Brand from Strapi v4 to Strapi 5

Overview

QBurst Technologies, a digital engineering company, partnered with a global luxury retail brand to elevate their content management capabilities. Over a focused three-month project, the team migrated the brand’s digital ecosystem from Strapi v4 to v5, enhancing performance, scalability, and editorial workflows. Leveraging a modern tech stack including Strapi, Next.js, Node.js, and AWS, QBurst helped the client future-proof their CMS infrastructure while delivering a seamless upgrade experience.

The Challenge

The client, a global luxury retail brand, had successfully used Strapi v4 to manage content across its website. While v4 had been a stable foundation, the upcoming transition to Strapi v5 opened up a valuable opportunity to strengthen their digital ecosystem:

• Future Support & Security: Migrating to v5 ensured ongoing access to official support, security patches, and new feature updates, keeping the platform resilient and secure.
• Roadmap Alignment: By moving to v5, the brand could immediately benefit from Strapi’s latest innovations and stay aligned with its long-term product roadmap.
• Operational Readiness: Replacing deprecated plugins and legacy APIs with modern alternatives created a stronger foundation for future integrations.
• Enhanced Editorial Experience: Business teams gained access to modern workflows like live preview, content history, and streamlined internationalization (i18n), enabling faster and more accurate content delivery.

To ensure long-term stability, scalability, and future-proofing, the client made the strategic decision to migrate to Strapi v5.

The Solution

We migrated the client’s CMS from Strapi v4 to v5 while ensuring uninterrupted business operations.

Key improvements delivered:

• Live Preview: Content editors could preview pages before publishing, reducing errors.
• Unified Document System: Drafts, published versions, and translations are consolidated under a single document model, simplifying consistency and version history.
• Flatter API Responses: APIs became cleaner and more efficient. Replacing nested attributes with flatter responses simplified integration with the frontend.
• Built-in Internationalization (i18n): In v5, i18n is built into the core (no plugin required), simplifying setup and making translation workflows more consistent.
• Official Strapi Client Library: v5 introduces an official client library, making it easier and more reliable to consume the Strapi API from frontend applications.
• Better Developer Experience: Stronger TypeScript support, a Plugin SDK, and faster admin UI bundling with Vite streamlines development.
• Support & Maintenance: v4 is moving toward end-of-life. Upgrading ensures access to security patches, updates, and the evolving plugin ecosystem.

The Implementation Process

We followed a structured migration approach to minimize risks:

1. Audit Plugins and Custom Code: Check all plugins for v5 compatibility. Review custom controllers, services, and middleware for deprecated API usage (entityService). Note that the Document Service API replaces the Entity Service API used in Strapi v4.
2. Full Backup: Database snapshots, media libraries, and customized codebases were secured prior to migration.
3. Upgrade Tool & Manual Adjustments: We used the official CLI upgrade tool and manually updated models, relations, and custom controllers.
4. Refactoring: Adjusted models, controllers, and bulk import logic to work with the new Document Service API.
5. Incremental Migration Strategy: A compatibility header (Strapi-Response-Format: v4) allowed the backend (running on v5) to return responses in the older v4 format. This ensured that existing frontends continued working while frontend applications were progressively updated to consume the new v5 response format.

Migration Results & Impact

The migration delivered measurable improvements:

• Editorial Efficiency: Preview and live preview features reduced publishing errors and made listing reviews faster.
• Performance Gains: API responses for searches became leaner, improving page load times.
• Code Quality: Cleaner backend architecture with Document Service reduced technical debt.
• Future Scalability: The CMS is now aligned with Strapi’s roadmap, ensuring supportability, plugin compatibility, and long-term maintainability.

Technical Deep Dive

1. Model Alignment

Content types and components were verified for v5 compatibility, and relational models (category, subcategory, brand) were adjusted to align with v5’s documentId-based relation handling.

2. CSV Import & Bulk Upsert

After upgrading to Strapi v5, the CSV import logic and bulk upsert controller broke due to the new Document Service API (which replaces the Entity Service) and changes in how relations and i18n translations are handled. To fix this :

• We refactored the Node.js CSV script and bulk upsert controller to use the Document Service API with documentId.
• Create base documents first and then attach translations.
• Adapt to the new i18n model.
• Manage relations with the new connection, disconnect, and set parameters.
• Pass documentIds instead of numeric IDs, and handle Strapi v5’s flattened relation response format.

3. Custom Controllers

Wishlist/account-related custom controllers required changes due to documentId and relation population changes in v5. All Entity Service APIs were migrated to Document Service APIs, and queries and update logic were refactored with normalized responses to maintain frontend compatibility.

4. BFF Layer

Strapi 5 introduced improved response structures and relation handling, which created an opportunity to modernize the BFF middleware. We refactored it to normalize v5 responses, adjust population logic, and ensure backward-compatible contracts with the FE. To make the transition smooth, we adopted an incremental migration strategy: initially serving all APIs with the Strapi-Response-Format: v4 header so the FE and BFF continued working without disruption, then gradually migrating APIs to the new v5 document service and response format while progressively removing the compatibility header.

5. Plugins

Some plugins were incompatible with Strapi v5, so we replaced them with supported alternatives and customized certain functionalities using the Plugin SDK (eg, SEO plugin, Content Versioning plugin).

6. Testing & Validation

Testing involved importing test CSVs (multi-locale), verifying BFF response contracts with the FE team, and ensuring personalization endpoints worked without FE changes.

Lessons Learned & Best Practices

For organizations considering the same migration, here are our key lessons:

• Always maintain backups and a rollback plan before touching production.
• Use compatibility headers to reduce disruption for frontend consumers.
• Validate new preview and draft workflows with content editors early.
• Keep plugins audited and avoid reliance on unsupported community packages.
• Pay extra attention to relations and i18n—these are the most complex parts of migration.

About QBurst

QBurst is a digital engineering company that crafts delightful client experiences through AI-driven software engineering and data solutions. They support clients in driving digital transformation that helps them innovate, scale, and succeed.

They are a High AI-Q company offering differentiated digital experiences to clients and their end-customers by infusing AI into every aspect of their delivery and operations.