Обновление 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

// Или создать compatibility layer:
function flattenStrapiData<T>(item: { id: number; attributes: T }): T & { id: number } {
  return { id: item.id, ...item.attributes }
}

Если фронтенд большой — можно включить compatibility mode в 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 с maintenance window

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

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

Некоторые плагины сообщества могут не иметь v5-версии — нужно искать альтернативы или ждать обновлений.

Сроки

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