Strapi v4 to v5 Migration: Turnkey CMS Upgrade

Imagine your Strapi v4 project runs smoothly, but you want TypeScript support and better performance. You run npx @strapi/upgrade major — and half of your API stops responding. Errors in the console, blank pages, broken endpoints. These are standard consequences of an unprepared upgrade. Strapi v5 is a major update with breaking changes: flat response structure instead of data.attributes, Entity Service replaced by Document Service, and a new draft/publish mechanism via status. Without a systematic approach, migration turns into a firefight that can take weeks and cost a lot. We have completed over 20 such migrations for projects of various scales — from small blogs to complex multilingual portals with dozens of content types. Our experience lets us go from v4 to v5 without downtime or data loss. Below is a real algorithm that will save you weeks of development and reduce the risk of missed deadlines.

Key API and Service Changes

Strapi v5 introduces several fundamental changes that require careful preparation.

API Response Format Change

In v4, each item was returned inside an envelope: { data: { id, attributes: {...} } }. In v5, the structure is flat:

{
  "id": 1,
  "documentId": "abc123",
  "title": "Article"
}

This breaks any frontend that accesses data.attributes.title. Without adaptation, users will see blank pages. For backward compatibility, Strapi v5 supports the environment variable STRAPI_RESPONSE_ENVELOPE=true. It makes the server temporarily return v4 format, giving you time to update the frontend without a full stop. However, this mode is not recommended for production — use it only as a transitional bridge.

Document Service vs Entity Service

All methods for working with entities have changed. Instead of strapi.entityService.findMany, use strapi.documents(...).findMany. The code below shows a typical replacement:

// v4
await strapi.entityService.findMany('api::article.article', {
  filters: { published: true },
  populate: ['author']
})

// v5
await strapi.documents('api::article.article').findMany({
  filters: { published: true },
  populate: ['author']
})

Draft/Publish via status Instead of publishedAt

In v5, the publication status is passed as a string: draft or published. This simplifies filtering but requires updating all queries.

How to Prepare the Frontend

The most common mistake is to update only the server. The frontend stops displaying content. Here is the plan:

1. Create a compatibility layer (adapter) on the frontend that temporarily transforms v4 format to v5. For example, a flattenStrapiData function:

function flattenStrapiData<T>(item: { id: number; attributes: T }): T & { id: number } {
  return { id: item.id, ...item.attributes }
}

2. Enable compatibility mode in Strapi v5 (option STRAPI_RESPONSE_ENVELOPE=true) so the server temporarily returns v4 format.

3. Go through all pages and replace data.attributes with direct access.

Plugin Compatibility and Tooling

Community plugins are a bottleneck. Check compatibility in the Strapi Marketplace. If a plugin is not updated to v5, you'll need to replace it with an alternative, fork and adapt it, or temporarily disable it. On a staging environment, run npm ls | grep strapi and check each line.

Strapi provides the CLI utility @strapi/upgrade and codemods. Run in this order:

npx @strapi/upgrade major
npx @strapi/codemods migrate

Codemods automatically replace most Entity Service calls with Document Service, update hooks and imports. But manual fixes remain — especially in custom controllers and lifecycle hooks.

Our Systematic Migration Approach

Our approach combines automation with deep expertise. We have migrated projects ranging from small blogs to enterprise portals with over 50 content types. For example, on a recent multilingual portal with custom plugins and a React frontend, we reduced the migration timeline from an estimated 4 weeks to just 10 days — that's 3x faster than typical DIY efforts. The result: zero downtime, no data loss, and a fully compatible frontend within the first week.

5-Step Migration Process

1. Audit of current version and dependencies — determine scope of work.
2. Upgrade Strapi to v5 on staging — isolated environment for testing.
3. Run codemods and manual fixes — automate Entity Service replacement.
4. Test API and frontend — check every endpoint.
5. Final deployment and monitoring — with stability guarantee.

What's Included in Turnkey Migration

Below is a typical scope of work. Average project cost: $2,999 (saves 2 weeks of development time).

The price includes:

• Consultation on breaking changes;
• Updating all project files;
• Fixing custom code (lifecycle hooks, services, policies);
• Configuring compatibility mode if necessary;
• Testing API compatibility (Postman collection);
• Documentation of changes and handover to team.

Guarantee: We support the project for 2 weeks after deployment — free of charge.

Comparison: v4 vs v5 in 30 Seconds

Strapi v5 is faster and more strictly typed — after migration, your project gets better DX and lower server load.

Contact us for a preliminary assessment of your project. We will prepare a migration plan in one day. Order a turnkey migration — get a stable v5 system without surprises.

Website Redesign and Migration: CMS Change, SEO Preservation

A client came to us 6 weeks after a self-attempted redesign: 'We moved from WordPress to Tilda, traffic dropped by 70%.' I opened Google Search Console — 847 pages returned 404, the URL structure had completely changed, not a single 301 redirect was in place. Yandex hadn't reindexed the new site yet, positions collapsed. Recovery took 4 months and resulted in significant revenue loss for the quarter. Our experience — over 7 years and 80+ successful migrations, we guarantee position retention with the right approach.

Why Do Migrations Break SEO?

Search engines have indexed specific URLs. If /catalog/shoes/nike-air-max-270 turned into /products/nike-air-max-270 without a 301 redirect — all the link equity, traffic, and rankings go nowhere. Google says 301 passes ~99% of PageRank, but in practice positions recover over 2–8 weeks, not instantly.

Commonly, SEO gets broken not out of malice, but because a developer doesn't view the URL structure as a public API. Here are typical breakages:

How to Recover Traffic After a Failed Migration?

If traffic dropped, act immediately:

1. Crawl the new site for 404s and compare with the pre-migration URL list.
2. Create redirects for all lost pages with traffic >0.
3. Check structured data and meta tags on a test sample.
4. Daily monitor Coverage in Search Console and positions for top 50 queries.
5. If after 2 weeks traffic does not recover — deep audit of redirects (transitivity, chains, loops).

In our practice, a large e-commerce site lost 50% of traffic when moving from Bitrix to React + Strapi. We restored 95% of redirects in three days, and within 3 weeks traffic returned to 90% of original.

What Does a Pre-Migration Audit Include?

Before starting development on the new site:

1. Full crawl of current site via Screaming Frog or Sitebulb. Get list of all indexable URLs with traffic from Google Search Console.
2. Export all pages with organic traffic >0 over the last 6 months — these are priority for redirects.
3. Record all external backlinks to specific pages — Ahrefs, Semrush.
4. Snapshot current positions for key queries — baseline for post-migration comparison.
5. Save Core Web Vitals from Search Console for the previous 90 days.

Table for recording:

Contact us for a detailed pre-migration audit — we will help identify all risks and create an action plan.

URL Mapping and Redirects

For projects with 200+ pages, we create a mapping table: old URL → new URL → status (301, merged with another page, deleted). Each row is verified: does the content actually migrate here?

In Laravel, redirects are handled via configuration file and middleware, not .htaccess — faster and more manageable. For WordPress → Next.js: redirects are set in next.config.js (static) and at the Nginx/CDN level for dynamic ones. Old .htaccess on shared hosting with 500+ lines of redirects is a special hell. Each redirect is checked sequentially, performance suffers. We move to Nginx map directive or Redis cache for dynamic lookup. More at Wikipedia: HTTP 301.

How to Migrate Content from Different CMSs?

WordPress → Headless CMS (Contentful, Strapi, Sanity): WordPress REST API or WP All Export to export posts, meta fields, media files. Migration script in Node.js: parse export, transform structure, upload via CMS API. Media files are reuploaded to new storage, links updated in content. Typical problem — shortcodes in WordPress content ([gallery id="123"]): need parser and transformation to new format.

1C-Bitrix → modern stack: Bitrix stores content in non-standard tables with IBLOCK_ELEMENT_PROPERTY. Direct SQL export via phpMyAdmin or Bitrix API. Transformation is the longest part due to specific Bitrix data structure.

Heavy WYSIWYG → structured content: Years of editing in FCKEditor/TinyMCE leave inline styles, non-standard tags, broken attributes. HTML sanitize + transformation to Markdown or Portable Text (Sanity) with manual check of problematic pages.

How to Preserve Technical SEO Elements During Migration?

Structured data (Schema.org) — if the old site had Product, Article, BreadcrumbList markup, they must be on the new site too. Google Search Console → Enhancement reports will show loss of rich snippets.

Sitemap XML: generated automatically, submitted to GSC a day after launch. Old sitemap remains until full reindexing.

hreflang for multilingual sites: if tags are lost during migration, conflicts between language versions in search results will start within weeks.

Open Graph and Twitter Card meta tags — often forgotten when changing template, pages stop displaying correctly when shared on social networks.

Launch and First Weeks Monitoring

DNS propagation: DNS switching takes up to 48 hours, plan launch with buffer. Cloudflare as DNS provider — propagation takes minutes, not hours.

After launch, monitor daily: Search Console → Coverage (indexing errors), Analytics → organic traffic, year-over-year comparison, crawl site for 404 errors.

First 2 weeks are critical. If traffic drops more than 30% — immediate audit of redirects and comparison with pre-migration crawl.

What the Service Includes

Results you receive:

1. Migration plan with URL mapping and redirects in Excel/Google Sheets format.
2. Configured 301 redirects at server level (Nginx/Cloudflare/Vercel).
3. Migrated content with integrity check: images, meta fields, links.
4. Structured data (Schema.org) on the new site, identical to old or improved.
5. SEO report: position trend at 1, 3, and 6 weeks after launch.
6. Coverage monitoring in Search Console with error notifications.
7. Guaranteed position retention: if traffic drops more than 15% within the first month — free audit and correction.

Timelines and Estimates

• Redesign with migration for a small site (up to 100 pages): 4–8 weeks.
• E-commerce migration with 500+ product pages: 8–16 weeks.
• Only technical migration part (redirects, metadata) without redesign: 1–3 weeks.

Cost is calculated individually based on scope.

Get a consultation for your project — we will respond within a day. Order a pre-migration audit of your site and receive a detailed proposal with a redirect plan. Contact us to discuss details.