Comment migrer de Strapi 4 vers Strapi 5 : Guide complet

La migration vers Strapi 5 n’est pas une simple mise à jour : c’est une refonte en profondeur. Ce guide vous accompagne étape par étape pour réussir votre transition, en intégrant les changements essentiels : nouveau modèle de documents, Document Service API, suppression de helper-plugin, etc.

1. Préparer votre environnement

Étape 1 — Sauvegarde

Sauvegardez votre projet Strapi 4 :

# Sauvegarde de la base de données pg_dump mydb > backup.sql # Copie du code source cp -r my-strapi4-project my-strapi4-backup

Étape 2 — Lister vos personnalisations

Notez tous les éléments personnalisés :

• /src/plugins

• /src/extensions

• Contrôleurs ou services modifiés

Étape 3 — Vérifier les versions

• Strapi 5 nécessite Node.js ≥ 18

• Vérifiez la compatibilité de vos dépendances (npm outdated)

2. Créer un nouveau projet Strapi 5

Il n’est pas possible de mettre à jour un projet existant. Créez un nouveau projet propre :

npx create-strapi-app@latest my-strapi5-project

Puis copiez :

• /src/api (types de contenu, contrôleurs, services)

• /src/plugins (vos plugins personnalisés uniquement)

• /config (à migrer progressivement)

3. Migrer les types de contenu

Étape 1 — Adapter les schémas

Strapi 4 :

{ "kind": "collectionType", "info": { "displayName": "Article" }, "attributes": { "title": { "type": "string" }, "content": { "type": "text" }, "author": { "type": "relation", "relation": "manyToOne", "target": "api::user.user" } } }

Strapi 5 :

{ "kind": "collectionType", "info": { "displayName": "Article" }, "options": { "draftAndPublish": true }, "attributes": { "title": { "type": "string" }, "content": { "type": "text" }, "author": { "type": "relation", "relation": "manyToOne", "target": "api::user.user" } } }

Changements principaux :

• L’ancien champ id est remplacé par documentId, géré automatiquement.

• Le mode Brouillon & Publication est intégré nativement dans les types de contenu.

4. Migrer de l’Entity Service vers le Document Service

Strapi 4 utilisait :

await strapi.entityService.findMany('api::article.article', { filters: { title: 'Hello' } });

Strapi 5 utilise désormais :

await strapi.documents('api::article.article').findMany({ filters: { title: 'Hello' }, status: 'published' // "draft" ou "published" });

Étapes à suivre :

• Remplacez partout strapi.entityService par strapi.documents.

• Remplacez les références à .id par .documentId.

• Mettez à jour les filtres :

  • publishedAt → status: 'published'

  • Pagination inchangée, mais syntaxe plus stricte.

5. Mettre à jour les plugins

Étape 1 — Supprimer helper-plugin

Le package @strapi/helper-plugin est supprimé. Remplacez :

import { request } from '@strapi/helper-plugin';

par :

import { request } from '@strapi/strapi/admin';

Étape 2 — Adapter la structure des plugins

Vos plugins doivent être structurés ainsi :

src/plugins/mon-plugin/ ├── strapi-admin.js ├── strapi-server.js └── package.json

Dans strapi-server.js :

export default () => ({ register() {}, bootstrap() {}, });

Étape 3 — Utiliser la Document Service API

Dans vos plugins, remplacez les appels à entityService par strapi.documents().

6. Mettre à jour la configuration et les middlewares

Les fichiers de configuration changent légèrement de syntaxe.

Strapi 4 :

module.exports = ({ env }) => ({ host: env('HOST', '0.0.0.0'), port: env.int('PORT', 1337), });

Strapi 5 :

import { defineConfig } from '@strapi/strapi'; export default defineConfig({ host: process.env.HOST || '0.0.0.0', port: parseInt(process.env.PORT) || 1337, });

Adaptez aussi :

• /config/database.js

• /config/middlewares.js

• /config/plugins.js

7. Migrer les données

Si votre contenu est limité et sans relations complexes, effectuez une exportation/importation manuelle :

# Exporter depuis Strapi 4 curl https://strapi4.example.com/api/articles?populate=* > articles.json

Puis importer dans Strapi 5 :

const axios = require('axios'); const data = require('./articles.json'); for (const item of data.data) { await axios.post('https://strapi5.example.com/api/articles', { data: { title: item.attributes.title, content: item.attributes.content, }, }); }

Si vous réutilisez la même base de données (avancé) :

• Ajoutez des colonnes documentId

• Mettez à jour les relations

• Vérifiez la cohérence des tables

8. Reconfigurer les rôles et permissions

Dans Strapi 5, le système de permissions est lié au cycle de vie des documents. Chaque type de contenu a désormais des actions : read, create, publish, unpublish, etc.

• Allez dans Paramètres → Rôles & Permissions

• Réactivez les routes nécessaires

• Testez les endpoints REST/GraphQL protégés

9. Tester et déployer

npm run develop

Vérifiez :

• L’interface d’administration

• Les types de contenu et relations

• Les API (avec documentId)

• Le bon fonctionnement des plugins

Ensuite, déployez suivant le guide officiel Strapi 5.