Guide pratique des mises à niveau et migrations Expo

Introduction

Mettre à niveau un projet Expo ne se résume pas à changer un numéro de version dans le fichier package.json. C'est un changement coordonné qui touche le SDK Expo, React Native, les projets natifs et souvent votre pipeline CI/CD. Sans processus clair, vous risquez des builds cassés, des modules natifs incompatibles et des erreurs d'exécution inattendues. Ce guide propose une approche pratique, basée sur des commandes, pour les mises à niveau et migrations Expo, destinée aux développeurs, consultants DevOps et équipes techniques de startups.

Nous aborderons :

Comment inventorier votre environnement Expo et React Native actuel.
Le chemin le plus sûr pour effectuer une mise à niveau, y compris les vérifications préalables et l'alignement des dépendances.
La vérification et le diagnostic pour confirmer que la mise à niveau a fonctionné.
Les modes d'échec courants et comment s'en remettre.
Une liste de contrôle opérationnelle concise que vous pourrez réutiliser pour de futures mises à niveau.

Tout au long, nous mettons l'accent sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter les étapes de récupération avant d'en avoir besoin. Vous trouverez des commandes concrètes avec les sorties attendues, les signaux d'échec et les chemins de retour en arrière.

Inventaire des versions et de l'environnement

Avant de toucher au moindre code, dressez un tableau complet de votre configuration actuelle. L'objectif est de savoir exactement ce que vous avez, ce qui est pris en charge et ce que requiert la version cible. Cela réduit les surprises et vous donne une base de référence pour le retour en arrière.

Identifier les versions actuelles

Exécutez ces commandes à la racine de votre projet (le répertoire contenant package.json) :

npx expo --version

Sortie attendue (exemple pour le SDK 46) :

4.12.0

node -v

Sortie attendue (doit respecter le minimum requis par Expo, par exemple v16.13.0 pour le SDK 46) :

v16.13.0

npx react-native --version

Sortie attendue :

0.69.6

Vérifiez la version exacte du SDK Expo dans votre package.json :

cat package.json | grep '"expo"'

Exemple de ligne :

"expo": "~46.0.0"

Inspectez également toutes les dépendances liées à React Native :

npm list react react-native expo

Sortie attendue (tronquée) :

[email protected] /path/to/project
├── [email protected]
├── [email protected]
└── [email protected]

Capturer la topologie de déploiement

Sachez où votre application s'exécute. Utilisez-vous Expo Go, un build de développement ou un binaire autonome ? Cela affecte la stratégie de mise à niveau et les tests.

Vérifiez votre app.json ou app.config.js pour les paramètres expo.ios et expo.android, et notez si vous utilisez EAS Build ou des builds locaux. Par exemple, un extrait typique de app.json :

{
  "expo": {
    "name": "MyApp",
    "slug": "myapp",
    "version": "1.0.0",
    "ios": {
      "bundleIdentifier": "com.example.myapp"
    },
    "android": {
      "package": "com.example.myapp"
    }
  }
}

Si vous utilisez EAS, exécutez :

eas build:list --platform all --limit 5

Cela liste les builds récents et leurs versions du SDK Expo, vous aidant à vous assurer que tous les builds utilisent la même version avant la mise à niveau.

Vérifier la compatibilité avec le SDK cible

Avant de procéder à la mise à niveau, consultez le guide officiel de mise à niveau Expo pour votre SDK cible. Par exemple, si vous passez du SDK 46 au 47, consultez le journal des modifications du SDK 47 d'Expo pour connaître les changements cassants et la version de React Native requise. Notez tout changement dans les paquets de base comme expo-av, expo-camera ou expo-notifications, car leurs API peuvent avoir évolué.

Documentez l'état actuel dans un tableau simple pour plus de clarté :

Composant	Version actuelle	Version cible	Compatible ?
Expo SDK	46.0.0	47.0.0	Oui
React Native	0.69.6	0.70.5	Oui
Node.js	16.13.0	>=16.13.0	Oui
expo-camera	~12.0.0	~13.0.0	Nécessite une revue de l'API

Cet inventaire devient votre référence de retour en arrière. Enregistrez une copie de package.json et, le cas échéant, de vos dossiers natifs (ios/ et android/) dans le contrôle de version avant d'apporter des modifications.

Chemin de configuration sûr

Le chemin de mise à niveau le plus sûr utilise les outils officiels d'Expo et suit une séquence contrôlée. Nous utiliserons expo upgrade pour aligner les dépendances, puis ajusterons manuellement la configuration si nécessaire.

Prérequis et vérifications préalables

Avant d'exécuter la mise à niveau, assurez-vous que votre répertoire de travail est propre et que toutes les modifications sont commitées :

git status --porcelain

Sortie attendue (vide si propre) :

Si des modifications existent, commitez-les ou mettez-les de côté. Créez ensuite une branche de sauvegarde :

git checkout -b upgrade/sdk-47

Vérifiez que vous disposez d'une sauvegarde récente de votre projet, surtout si vous n'utilisez pas de contrôle de version. Une simple commande de copie :

cp -R /path/to/project /path/to/project-backup-sdk46

Remarque : ne stockez jamais de véritables informations d'identification, jetons ou clés privées dans votre dépôt. Utilisez des variables d'environnement ou des fichiers .env exclus du contrôle de version.

Exécuter la mise à niveau Expo

Utilisez la commande de mise à niveau officielle :

npx expo upgrade

Cette commande va :

Déterminer la version du SDK compatible la plus récente.
Mettre à jour les dépendances de package.json vers les versions recommandées.
Installer les nouvelles dépendances avec npm ou yarn (selon votre fichier de verrouillage).
Exécuter les scripts post-installation nécessaires.

Sortie attendue (extrait d'exemple) :

? You are currently using SDK 46.0.0. Would you like to upgrade to SDK 47.0.0? Yes
Updating packages...
- expo: 46.0.0 -> 47.0.0
- react-native: 0.69.6 -> 0.70.5
- expo-camera: 12.0.0 -> 13.0.0
...
Installing dependencies...
added 25 packages, removed 12 packages, changed 40 packages

Si vous devez mettre à niveau vers une version spécifique du SDK, utilisez :

npx expo upgrade 47.0.0

Après la mise à niveau automatique, inspectez les modifications dans package.json avec :

git diff package.json

Vérifiez que toutes les versions correspondent aux versions attendues pour le SDK cible. Pour le SDK 47, les versions clés attendues sont :

Expo : ~47.0.0
React Native : 0.70.5
React : 18.1.0

Ajustements manuels de configuration

Certaines mises à niveau nécessitent des modifications manuelles des fichiers de configuration. Par exemple, dans le SDK 47, la configuration de expo-splash-screen a été déplacée vers un plugin. Vous devrez peut-être mettre à jour app.json comme suit :

Avant (SDK 46) :

{
  "expo": {
    "splash": {
      "image": "./assets/splash.png",
      "resizeMode": "contain",
      "backgroundColor": "#ffffff"
    }
  }
}

Après (SDK 47) :

{
  "expo": {
    "plugins": [
      [
        "expo-splash-screen",
        {
          "image": "./assets/splash.png",
          "resizeMode": "contain",
          "backgroundColor": "#ffffff"
        }
      ]
    ]
  }
}

Consultez le guide de mise à niveau pour tout changement cassant nécessitant votre attention. Par exemple, si vous utilisez expo-av, notez que dans le SDK 47, la prop useNativeControls du composant Video a été dépréciée au profit de useNativeControls à l'intérieur de videoStyle. Mettez à jour votre code en conséquence.

Limitation du rayon d'impact

Pour limiter l'impact de la mise à niveau, envisagez de la faire par étapes si vous avez un grand projet. Par exemple, mettez d'abord à niveau uniquement les paquets de base d'Expo et React Native, puis mettez à niveau séparément les bibliothèques dépendantes comme expo-camera ou expo-notifications. Cela facilite l'isolation des problèmes.

Après tout changement, exécutez les étapes de vérification de la section suivante avant de continuer.

Vérification et diagnostics

Après la mise à niveau, vous devez vérifier que l'application se construit et s'exécute correctement. Cela implique des vérifications statiques, le bundling et éventuellement l'exécution de l'application sur un simulateur ou un appareil.

Vérifications statiques

Vérification TypeScript

Si votre projet utilise TypeScript, exécutez :

npx tsc --noEmit

Sortie attendue (si aucune erreur) :

Si des erreurs apparaissent, corrigez-les. Par exemple, une erreur courante après la mise à niveau vers le SDK 47 avec expo-camera :

Type 'Camera' is missing the following properties from type 'CameraType': getSupportedRatiosAsync, ...

Cela indique que l'API de la bibliothèque a changé et que vous devez mettre à jour votre utilisation.

Vérification du linter

Exécutez votre linter (par exemple, ESLint) :

npx eslint .

Sortie attendue :

En cas d'avertissements, priorisez ceux liés aux nouvelles dépréciations ou aux API modifiées.

Vérification du bundle

Générez un bundle de production pour détecter les erreurs de résolution de modules :

npx expo export --platform all

Sortie attendue :

Exporting iOS bundle...
Exporting Android bundle...
Export successful

Si l'export échoue, le message d'erreur pointera vers le module problématique. Par exemple :

Unable to resolve module 'some-package' from 'src/App.tsx'

Cela signifie généralement qu'un paquet est manquant ou incompatible avec le nouveau SDK.

Vérification à l'exécution

Si possible, exécutez l'application en utilisant Expo Go ou un build de développement sur un simulateur/émulateur.

Démarrez le serveur de développement :

npx expo start

Appuyez ensuite sur i pour le simulateur iOS ou a pour l'émulateur Android. Observez le lancement de l'application. Testez les fonctionnalités clés, en particulier celles utilisant des bibliothèques mises à niveau.

Pour une vérification plus approfondie, utilisez EAS Build pour créer un build de développement et testez sur un appareil réel.

Commandes de diagnostic

Si l'application ne démarre pas, collectez des diagnostics :

npx expo-doctor

Sortie attendue (saine) :

✔ Check Expo config
✔ Check package.json
✔ Check dependencies
✔ Check for common project issues
All checks passed

Si des problèmes sont détectés, expo-doctor fournit des suggestions. Par exemple, s'il y a des dépendances dupliquées :

✖ Check dependencies
  Found duplicated packages: react-native, react
  Run `npx expo install --fix` to resolve.

Exécutez la commande de correction :

npx expo install --fix

Consultez les journaux natifs si vous utilisez un build de développement :

npx react-native log-ios

npx react-native log-android

Recherchez les erreurs liées à l'enregistrement des modules natifs ou aux modules manquants.

Modes d'échec et récupération

Même avec une planification minutieuse, les mises à niveau peuvent échouer. Voici les modes d'échec courants, leurs symptômes et les étapes de récupération.

Conflits de versions de dépendances

Symptôme : npm install ou yarn install échoue avec des erreurs de dépendances de pairs.

Exemple d'erreur :

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/react-native
npm ERR!   react-native@"0.70.5" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react-native@"^0.69.0" from [email protected]

Récupération :

Assurez-vous que tous les paquets liés à Expo sont mis à jour vers des versions compatibles avec le nouveau SDK. Utilisez npx expo install pour obtenir les versions recommandées.

npx expo install expo-camera

Si nécessaire, ajustez manuellement package.json et exécutez npm install avec --force ou --legacy-peer-deps comme mesure temporaire, puis résolvez correctement les conflits.

Incompatibilité de module natif

Symptôme : l'application se construit mais plante à l'exécution, souvent avec une erreur en boîte rouge comme :

Invariant Violation: Native module cannot be null.

TypeError: null is not an object (evaluating 'NativeModules.SomeModule')

Récupération :

Identifiez le module à l'origine du problème (par exemple, ExpoCamera).
Vérifiez si le code natif du module est inclus dans le build. Pour les builds de développement, assurez-vous d'avoir reconstruit après l'ajout du paquet.

expo run:android

expo run:ios

Si vous utilisez un client de développement personnalisé, reconstruisez-le avec les nouveaux modules.

Erreurs de bundling

Symptôme : le bundler Metro échoue avec « Unable to resolve module » ou des erreurs de syntaxe.

Exemple :

Unable to resolve module 'react-native-gesture-handler' from 'src/navigation/AppNavigator.tsx'

Récupération :

Installez le paquet manquant avec npx expo install react-native-gesture-handler.
Si le module existe mais est incompatible, videz le cache de Metro :

npx expo start --clear

Si l'erreur fait référence à un problème de transpilation (par exemple, jeton import inattendu), vérifiez votre babel.config.js. Assurez-vous qu'il inclut babel-preset-expo et tous les plugins nécessaires.

Dérive de configuration

Symptôme : le comportement de l'application change après la mise à niveau, par exemple l'écran de démarrage ne s'affiche pas ou les autorisations ne sont pas demandées.

Récupération :

Consultez le journal des modifications du SDK Expo pour les changements dans les plugins de configuration. Par exemple, dans le SDK 47, plusieurs modules nécessitent désormais une configuration explicite du plugin dans app.json.
Comparez votre app.json avec la configuration par défaut générée par npx expo prebuild (si vous utilisez CNG) ou référez-vous à la documentation.
Réexécutez npx expo prebuild --clean pour régénérer les projets natifs avec la configuration actuelle. Soyez prudent car cela écrasera les modifications natives.

Stratégie de retour en arrière

Si la mise à niveau provoque des problèmes irrésolubles, revenez à la version précédente.

Arrêtez tous les processus en cours.
Si vous avez créé une branche de sauvegarde, basculez dessus :

git checkout main

Restaurez le package.json et les dossiers natifs d'origine depuis la sauvegarde :

git checkout main -- package.json ios android

Réinstallez les dépendances :

rm -rf node_modules
npm install

Vérifiez avec npx expo-doctor et un contrôle de bundle.

Si vous avez utilisé une sauvegarde complète du projet (copie de dossier), remplacez simplement le dossier du projet par la sauvegarde.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle pour chaque mise à niveau Expo afin d'assurer la cohérence et de réduire les risques. Chaque élément comprend un exemple représentatif avec le responsable et le résultat attendu.

Avant la mise à niveau

[ ] Sauvegarder l'état actuel : Créez une branche git et/ou une sauvegarde de dossier. (Responsable : Développeur, par exemple Alex Chen, git checkout -b backup/sdk46)
[ ] Enregistrer les versions actuelles : Exécutez npx expo --version, node -v, npx react-native --version. Stockez la sortie dans un document. (Responsable : DevOps, par exemple Priya Shah)
[ ] Examiner le journal des modifications du SDK cible : Notez les changements cassants et les mises à jour requises. (Responsable : Lead technique, par exemple Jordan Lee)
[ ] Vérifier la configuration CI/CD : Assurez-vous que le pipeline de build est compatible avec les nouvelles versions. Mettez à jour si nécessaire. (Responsable : DevOps)
[ ] Vérifier un répertoire de travail propre : git status ne doit montrer aucun changement non commité. (Responsable : Développeur)

Exécution de la mise à niveau

[ ] Exécuter la commande de mise à niveau : npx expo upgrade (ou version spécifique). (Responsable : Développeur)
[ ] Résoudre les conflits de dépendances : Utilisez npx expo install --fix si nécessaire. (Responsable : Développeur)
[ ] Appliquer les modifications manuelles de configuration : Mettez à jour app.json, babel.config.js, etc., conformément au journal des modifications. (Responsable : Développeur)
[ ] Mettre à jour le code pour les changements d'API cassants : Ajustez l'utilisation des composants. (Responsable : Développeur)

Vérification

[ ] Exécuter les vérifications statiques : npx tsc --noEmit, npx eslint .. Assurez-vous qu'il n'y a aucune erreur. (Responsable : Développeur)
[ ] Exporter le bundle : npx expo export --platform all. Confirmez le succès. (Responsable : Développeur)
[ ] Exécuter sur simulateur/appareil : Testez les fonctionnalités critiques. (Responsable : QA, par exemple Sam Rodriguez)
[ ] Exécuter npx expo-doctor : Confirmez que tous les contrôles passent. (Responsable : Développeur)
[ ] Test de fumée des performances : Comparez le temps de démarrage de l'application et l'utilisation de la mémoire avant/après la mise à niveau. Enregistrez les métriques. (Responsable : QA)

Après la mise à niveau

[ ] Mettre à jour la documentation : Notez les nouvelles versions et tout changement de configuration dans le README. (Responsable : Rédacteur technique, par exemple Morgan Smith)
[ ] Commiter les modifications : Créez un message de commit significatif, par exemple « Mise à niveau vers Expo SDK 47 ». (Responsable : Développeur)
[ ] Étiqueter la version : Étiquetez le commit pour une référence facile de retour en arrière, par exemple git tag sdk-47. (Responsable : Gestionnaire de version)
[ ] Surveiller la production : Observez les taux d'erreur et les plantages via vos analyses. (Responsable : SRE, par exemple Taylor Brown)

Conclusion

Les mises à niveau Expo sont gérables lorsque vous suivez un processus structuré : inventoriez votre environnement, utilisez l'outil de mise à niveau officiel, vérifiez soigneusement et connaissez vos options de retour en arrière. Ce guide a fourni des commandes concrètes, des sorties attendues et des chemins de récupération pour vous aider à naviguer dans le processus en toute confiance.

Les points clés à retenir sont :

Observer avant de modifier : Capturez toujours l'état actuel et les versions.
Limiter le rayon d'impact : Utilisez le contrôle de version, les branches et les mises à niveau par étapes.
Vérifier avec des commandes réelles : Utilisez expo-doctor, les vérifications TypeScript, les exports de bundle et les tests à l'exécution.
Documenter la récupération : Ayez un plan de retour en arrière testé.

Comme prochaine étape, choisissez une vérification à faible risque pour votre projet Expo actuel. Exécutez les commandes d'inventaire et enregistrez les résultats. Ensuite, lorsque vous serez prêt à mettre à niveau, suivez la liste de contrôle et adaptez les exemples à vos dépendances spécifiques. Pour en savoir plus, consultez la documentation officielle de mise à niveau Expo et le journal des modifications de votre SDK cible.

N'oubliez pas : un flux de travail technique fiable rend les échecs visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision.

Guide pratique des mises à niveau et migrations Expo

Introduction

Inventaire des versions et de l'environnement

Identifier les versions actuelles

Capturer la topologie de déploiement

Vérifier la compatibilité avec le SDK cible

Chemin de configuration sûr

Prérequis et vérifications préalables

Exécuter la mise à niveau Expo

Ajustements manuels de configuration

Limitation du rayon d'impact

Vérification et diagnostics

Vérifications statiques

Vérification TypeScript

Vérification du linter

Vérification du bundle

Vérification à l'exécution

Commandes de diagnostic

Modes d'échec et récupération

Conflits de versions de dépendances

Incompatibilité de module natif

Erreurs de bundling

Dérive de configuration

Stratégie de retour en arrière

Liste de contrôle opérationnelle

Avant la mise à niveau

Exécution de la mise à niveau

Vérification

Après la mise à niveau

Conclusion

Recherches connexes

Score de qualité de l’article