Оновлення Strapi v4 на Strapi v5

Оновлення Strapi v4 на Strapi v5

Strapi v5 — це мажорне оновлення з breaking changes. Головні зміни: новий формат відповіді API (пласка структура замість data.attributes), новий Document Service замість Entity Service, оновлений TypeScript.

Ключові зміни

Формат відповіді API:

// Strapi v4
{
  "data": {
    "id": 1,
    "attributes": { "title": "Article", "slug": "article" }
  }
}

// Strapi v5
{
  "id": 1,
  "documentId": "abc123",
  "title": "Article",
  "slug": "article"
}

Document Service замість Entity Service:

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

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

Draft/Publish через status замість publishedAt:

// v4
{ filters: { publishedAt: { $notNull: true } } }

// v5
{ status: 'published' }

Офіційний інструмент міграції

# Оновити Strapi
npx @strapi/upgrade major

# Або поетапно:
npm install @strapi/strapi@5 @strapi/plugin-graphql@5 # та інші плагіни

# Запустити codemods для автоматичних змін
npx @strapi/codemods migrate

Codemods автоматично оновлять:

• Entity Service → Document Service
• Застарілі хуки життєвого циклу
• Імпорти з @strapi/strapi

Оновлення фронтенду

Фронтенд потрібно оновити під новий формат відповіді:

// До (v4)
const getTitle = (data: any) => data.attributes.title

// Після (v5)
const getTitle = (data: any) => data.title

// Або створити шар сумісності:
function flattenStrapiData<T>(item: { id: number; attributes: T }): T & { id: number } {
  return { id: item.id, ...item.attributes }
}

Якщо фронтенд великий — можна включити режим сумісності у v5:

// config/features.js
module.exports = { contentReleasesEnabled: true }

// Або через env:
STRAPI_RESPONSE_ENVELOPE=true  // повертає формат, сумісний з v4

Порядок оновлення

1. Оновіть Strapi у staging-середовищі
2. Запустіть npx @strapi/codemods migrate на серверному коді
3. Запустіть тести API — знайдіть місця зі змінени форматом
4. Оновіть фронтенд під новий формат
5. Протестуйте весь сайт
6. Розгорніть у production з вікном обслуговування

Перевірка сумісності плагінів

# Перевірити всі плагіни на сумісність з v5
npm ls | grep strapi
# Для кожного плагіну перевірте: https://market.strapi.io

Деякі плагіни спільноти можуть не мати v5-версії — потрібно шукати альтернативи або чекати оновлень.

Часові рамки

Міграція середнього проекту (5–8 типів контенту, власні контролери, фронтенд) — 3–5 днів за умови, що фронтенд не величезний.