Guide de mise à niveau vers Strapi 5 : migration depuis Strapi 4

Mettre à niveau un projet Strapi 4 vers Strapi 5 est un processus simple si vous suivez une checklist disciplinée : sauvegarder vos données, aligner l’environnement d’exécution, mettre à jour le cœur et les plugins, ajuster la configuration, migrer le code personnalisé et vérifier l’intégration front‑end. À chaque étape, vous conservez l’historique du contenu, les verrous d’édition et les journaux d’audit, et votre site Next.js continue de récupérer la même forme d’API.

1. Prérequis

Assurez‑vous d’avoir une copie de travail propre et que tous les changements locaux soient commités.

2. Sauvegardez tout

Même si la migration ne touche pas le schéma de la base de données, une sauvegarde complète vous protège contre toute perte de données inattendue.

# Exemple PostgreSQL
pg_dump -U <user> -h <host> -Fc -f strapi_backup.dump <db_name>

# Exemple MySQL
mysqldump -u <user> -p<password> <db_name> > strapi_backup.sql

Si vous utilisez le plugin Revisionary, son journal d’audit et sa corbeille sont stockés dans la même base de données, ils sont donc inclus dans le dump. Conservez le fichier de dump dans un endroit sécurisé et, si possible, testez une restauration sur un serveur de staging.

3. Mettez à jour les dépendances du projet

3.1. Modifiez la version de Strapi dans package.json

Remplacez les paquets Strapi 4 par leurs équivalents Strapi 5. La plupart des paquets du cœur conservent le même nom, seul le numéro de version majeure change.

// package.json (extrait)
"dependencies": {
  "@strapi/strapi": "^5.0.0",
  "@strapi/plugin-i18n": "^5.0.0",
  "@strapi/plugin-users-permissions": "^5.0.0",
  // autres plugins …
}

Si vous utilisez des plugins communautaires, vérifiez leurs pages npm pour une version compatible Strapi 5. Si aucune n’existe, vous devrez soit remplacer le plugin, soit différer la mise à jour.

3.2. Installez les nouvelles dépendances

npm install   # ou yarn install

Durant l’installation, vous pourriez voir des avertissements de peer‑dependency. Résolvez‑les en mettant à jour les paquets indiqués vers leurs versions Strapi 5.

4. Ajustez les fichiers de configuration

Strapi 5 introduit une nouvelle structure pour config/plugins.ts. L’ancien format config/plugins.js fonctionne toujours après un simple renommage, mais il est recommandé d’adopter le format typé pour éviter les erreurs d’exécution.

// config/plugins.ts (nouveau format)
export default ({ env }) => ({
  // Exemple : conserver la configuration du plugin Revisionary
  revisionary: {
    enabled: true,
    // Aucun changement majeur pour le plugin pour l’instant, mais surveillez les futures versions.
  },
  // autres plugins …
});

Si vous avez des variables d’environnement personnalisées, déplacez‑les vers la nouvelle structure config/env/{environment}.js comme décrit dans le guide Configuration (/docs/reference/configuration).

5. Examinez les changements majeurs dans les API du cœur

5.1. Document Service API

L’API Document Service nécessite désormais une gestion explicite de la locale pour les requêtes localisées. Si vous appeliez auparavant strapi.services.article.find(params), mettez à jour l’appel en incluant la locale le cas échéant.

// Avant (Strapi 4)
const articles = await strapi.services.article.find({ _limit: 10 });

// Après (Strapi 5)
const articles = await strapi.documents('api::article.article').find({
  locale: 'en',
  limit: 10,
});

Lisez les notes complètes de migration dans la documentation officielle de Strapi pour le Document Service.

5.2. Modifications i18n

Le plugin i18n stocke maintenant la locale par défaut dans config/i18n.js et attend le champ locale sur chaque entrée. Adaptez toutes les requêtes personnalisées qui s’appuyaient sur le fallback de la locale par défaut.

// Exemple de requête sensible à la locale
const post = await strapi.documents('api::post.post').findOne(id, {
  locale: 'fr',
});

5.3. Routes, contrôleurs et services

Les fichiers de routes auto‑générés sont passés de api/<name>/config/routes.json à src/api/<name>/routes/<name>.js. Si vous avez des routes personnalisées, copiez‑les dans la nouvelle arborescence et renommez l’export au nouveau format :

// src/api/article/routes/article.ts
export default {
  routes: [
    {
      method: 'GET',
      path: '/articles',
      handler: 'api::article.article.find',
    },
  ],
};

Les contrôleurs et services suivent le même déplacement de dossiers (src/api/<name>/controllers et src/api/<name>/services). Mettez à jour les importations relatives en conséquence.

6. Migrez les données du plugin Revisionary

Revisionary stocke les entrées versionnées dans des tables dédiées compatibles avec Strapi 5. Après la mise à jour du cœur, exécutez la commande de migration du plugin (si le plugin en fournit une). Au moment de la rédaction, le plugin détecte automatiquement la version de Strapi et effectue une migration silencieuse au premier démarrage.

npm run build   # construit l’interface d’administration
npm run start   # démarre Strapi ; le plugin migre ses tables

Vérifiez que le panneau Version history apparaît dans le Content Manager et que le Audit log montre les actions récentes (/docs/everyday-use/history). Si le panneau est absent, consultez le guide de dépannage (/docs/troubleshooting).

7. Testez le back‑end localement

1. Démarrez Strapi en mode développement :

   npm run develop

2. Ouvrez l’interface d’administration (http://localhost:1337/admin).
3. Vérifiez que tous les types de contenu se chargent, que le panneau Revisionary affiche les entrées, et que vous pouvez créer un brouillon, le publier et restaurer une version précédente.
4. Appelez le point de contrôle de santé intégré (/admin/health) pour confirmer que le serveur ne signale aucune erreur.

Si un code personnalisé lève ReferenceError: strapi.services is not defined, remplacez‑le par le nouveau schéma d’appel du Document Service.

8. Vérifiez le front‑end Next.js

La plupart des projets Next.js consomment Strapi via les endpoints REST ou GraphQL. La forme REST reste inchangée pour les champs de base, mais la gestion de la locale et les chemins du Document Service diffèrent.

8.1. Mettez à jour le client API

Si vous utilisez fetch('/api/articles'), vous devrez peut‑être ajouter le paramètre de requête locale pour les sites multilingues.

// pages/api/articles.js (route API Next.js)
export default async function handler(req, res) {
  const locale = req.query.locale || 'en';
  const response = await fetch(`${process.env.STRAPI_URL}/api/articles?locale=${locale}`);
  const data = await response.json();
  res.status(200).json(data);
}

Pour GraphQL, l’endpoint reste /graphql, mais le schéma inclut désormais l’argument locale sur chaque champ de requête.

8.2. Exécutez le front‑end localement

cd next-app
npm run dev

Visitez le site et confirmez que le contenu se charge, que l’aperçu des brouillons fonctionne (si vous utilisez le mode d’aperçu Draft & Publish) et que la navigation n’est pas affectée.

9. Déployez en production

1. Compilez l’interface d’administration de Strapi :

   npm run build

2. Copiez le dossier build/ généré sur votre serveur de production ou dans votre image de conteneur.
3. Assurez‑vous que les variables d’environnement (DATABASE_URL, HOST, STRAPI_ADMIN_JWT_SECRET, etc.) correspondent aux valeurs de production.
4. Redémarrez le processus Strapi.
5. Surveillez les logs pour détecter d’éventuels avertissements de migration.

Si vous déployez avec Docker, mettez à jour le Dockerfile pour utiliser une image de base Node 18 et réinstallez les dépendances avec la nouvelle version.

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/build ./build
COPY package*.json ./
RUN npm ci --only=production
EXPOSE 1337
CMD ["node", "./build"]

10. Checklist post‑migration

• Tous les types de contenu apparaissent dans l’interface d’administration.
• L’historique des versions, la corbeille et le journal d’audit de Revisionary fonctionnent.
• Les plugins personnalisés sont soit mis à jour, soit désactivés.
• Le front‑end Next.js affiche le contenu pour chaque locale utilisée.
• Les tests automatisés (le cas échéant) réussissent contre la nouvelle API.
• Les fichiers de sauvegarde sont stockés en lieu sûr et un test de restauration a été effectué.

Suivre cette checklist vous assure que la migration ne perturbera ni les éditeurs ni les utilisateurs finaux.

11. Problèmes courants et comment les éviter

12. Quand envisager une installation neuve plutôt qu’une mise à jour in‑place

Si votre projet dépend fortement de plugins qui n’ont pas d’équivalent Strapi 5, ou si le code personnalisé est étroitement couplé aux internals de Strapi 4, une nouvelle installation de Strapi 5 avec import de données (grâce à la fonction d’Export/Import de contenu) peut être plus rapide. L’export se réalise depuis l’interface d’administration (Settings → Export data) puis s’importe dans la nouvelle instance.

Conclusion

Migrer de Strapi 4 vers Strapi 5 ne nécessite pas une réécriture totale ; il s’agit d’une série d’étapes bien définies : sauvegarde, mise à jour des dépendances, ajustement de la configuration, migration du code personnalisé, vérification du plugin Revisionary et tests du front‑end Next.js. En suivant la checklist ci‑dessus, vous conservez l’historique du contenu, les verrous d’édition et les journaux d’audit, tout en profitant du nouveau Document Service, d’une meilleure gestion i18n et des gains de performance de Strapi 5.