## Intro

Les commandes Expo sont des outils quotidiens pour les développeurs React Native, les ingénieurs DevOps et les équipes techniques qui doivent passer d'un problème observé à un résultat vérifié sans conjecture. Ce guide se concentre sur les commandes que vous exécuterez réellement : vérifier votre environnement, créer et démarrer des projets, construire des binaires, diagnostiquer les problèmes et récupérer après des échecs. Chaque commande inclut les prérequis, un exemple concret avec des espaces réservés, la sortie attendue, un signal d'échec et une procédure de récupération.

L'objectif est la sécurité opérationnelle. Observez avant de modifier, limitez le rayon d'impact, utilisez des espaces réservés plutôt que des secrets, vérifiez le résultat et documentez comment récupérer si l'état attendu n'est pas atteint. Que vous intégriez un nouveau coéquipier ou déboguiez un pipeline CI, ce guide vous fournit les commandes exactes et leur contexte réel.

## Inventaire de version et d'environnement

Avant d'exécuter toute commande Expo, vous avez besoin d'un instantané clair de votre environnement. La première commande est toujours npx expo --version . Cette vérification en lecture seule vous indique quelle version de l'interface de ligne de commande Expo est installée et si votre version de Node.js répond aux exigences. Exemple de sortie attendue :

7.0.3

Si vous voyez une erreur comme npx: command not found , Node.js est manquant ou n'est pas dans le PATH. Installez Node.js 18 ou plus récent depuis le site officiel, puis vérifiez avec node --version (attendu : v18.16.0 ou supérieur) et npm --version (attendu : 9.5.1 ou supérieur).

Pour un diagnostic complet, exécutez npx expo-doctor . Cette commande vérifie les mauvaises configurations courantes telles que les versions de paquets incompatibles, les dépendances manquantes et les problèmes avec app.json. Exemple de sortie attendue :

All checks passed

Si expo-doctor signale des erreurs, corrigez chaque élément signalé un par un. Par exemple, s'il indique package.json: The following packages are not compatible with Expo SDK 49 , mettez à jour les paquets listés avec npx expo install <nom-du-paquet> et relancez expo-doctor jusqu'à ce qu'il passe.

Pour capturer l'état actuel à des fins de dépannage, enregistrez la sortie de ces commandes dans un fichier avec horodatage :

npx expo --version > expo-env-$(date +%Y%m%d-%H%M).txt && npx expo-doctor >> expo-env-$(date +%Y%m%d-%H%M).txt

Cela vous donne un instantané vérifiable avant tout changement. N'incluez jamais de véritables identifiants ou jetons dans ces journaux.

## Initialisation et démarrage du projet

Le flux de travail le plus courant consiste à créer un nouveau projet Expo et à démarrer le serveur de développement. Utilisez npx create-expo-app avec un nom de projet clair :

npx create-expo-app mon-app --template blank

Cette commande échafaude un projet minimal. La sortie attendue se termine par Project ready! et des instructions pour exécuter cd mon-app et npx expo start . Si la commande échoue avec une erreur réseau, vérifiez l'accès à votre registre npm et réessayez avec --registry https://registry.npmjs.org .

Pour démarrer le serveur de développement, accédez au répertoire du projet et exécutez :

npx expo start

La sortie attendue affiche un code QR et une liste d'options (appuyez sur a pour Android, i pour iOS, w pour le web). Sur un appareil physique, installez Expo Go depuis la boutique d'applications, scannez le code QR et votre projet se charge. Si le code QR n'apparaît pas, le serveur peut être incapable de se lier au port ; essayez npx expo start --port 8082 et scannez le code QR mis à jour.

Pour les environnements CI ou sans interface graphique, démarrez sans l'interface interactive :

npx expo start --no-dev --minify

Cela exécute un serveur similaire à la production. Vérifiez qu'il fonctionne en consultant la sortie du terminal pour Metro waiting on http://localhost:8081 .

## Configuration et modifications sécurisées

La configuration Expo se trouve dans app.json et package.json . Avant de modifier, sauvegardez le fichier actuel et notez la modification que vous avez l'intention d'apporter. Exemple :

cp app.json app.json.bak

Une modification sûre courante consiste à définir le nom de l'application et le slug. Dans app.json , mettez à jour les champs name et slug pour correspondre à votre projet :

{
 "expo": {
 "name": "MyApp",
 "slug": "my-app",
 "version": "1.0.0",
 "orientation": "portrait",
 "icon": "./assets/icon.png",
 "userInterfaceStyle": "light",
 "splash": {
 "image": "./assets/splash.png",
 "resizeMode": "contain",
 "backgroundColor": "#ffffff"
 },
 "assetBundlePatterns": [
 "**/*"
 ],
 "ios": {
 "supportsTablet": true
 },
 "android": {
 "adaptiveIcon": {
 "foregroundImage": "./assets/adaptive-icon.png",
 "backgroundColor": "#ffffff"
 }
 },
 "web": {
 "favicon": "./assets/favicon.png"
 }
 }
} 
 Après modification, validez la configuration avec npx expo config --type public . Cela imprime la configuration résolue et détecte les erreurs de syntaxe. La sortie attendue est un objet JSON sans erreurs. Si vous voyez Error parsing app.json , revérifiez votre syntaxe JSON, puis restaurez à partir de la sauvegarde si nécessaire avec cp app.json.bak app.json .

Pour les valeurs spécifiques à l'environnement, utilisez app.config.js et les variables d'environnement. Exemple :

module.exports = {
 expo: {
 name: process.env.APP_NAME || 'MyApp',
 slug: 'my-app',
 extra: {
 apiUrl: process.env.API_URL || 'https://api.example.com',
 },
 },
}; 
 Exécutez avec API_URL=https://staging.example.com npx expo start et vérifiez en journalisant Constants.expoConfig.extra.apiUrl dans votre application. Ne codez jamais en dur les secrets de production.

## Construction et publication

Pour les builds de test, utilisez Expo Application Services (EAS) avec eas build . Installez d'abord l'interface de ligne de commande EAS :

npm install -g eas-cli

Ensuite, connectez-vous et configurez :

eas login eas build:configure

La commande configure crée eas.json avec des profils de build par défaut. Pour créer un APK Android pour les tests :

eas build -p android --profile preview

Sortie attendue : EAS démarre un build dans le cloud et fournit une URL pour surveiller la progression. Le build prend généralement 10 à 20 minutes. Vous recevez un lien de téléchargement lorsqu'il est terminé. Les signaux d'échec incluent des identifiants manquants ou une configuration d'application invalide. Pour récupérer, exécutez à nouveau eas build:configure et assurez-vous que votre app.json est valide.

Pour un build de production, utilisez le profil production avec incrément de version :

eas build -p android --profile production --auto-submit

Cela déclenche un build et une soumission au Play Store si configuré. Testez toujours le build de prévisualisation d'abord.

Pour publier une mise à jour over-the-air sans build complet, utilisez expo publish (hérité) ou eas update :

eas update --branch production --message "Correction du crash à la connexion"

La sortie attendue montre l'URL de mise à jour et l'ID de groupe. Les utilisateurs avec Expo Go ou un build de développement reçoivent la mise à jour au prochain lancement. Si la mise à jour échoue, vérifiez le nom de votre branche et assurez-vous que le projet est lié à EAS.

## Vérification et diagnostic

Après avoir démarré le serveur ou apporté des modifications, vérifiez que votre application se charge et fonctionne. Utilisez les journaux du bundler Metro pour confirmer la création du bundle. Sortie attendue dans le terminal :

iOS Bundled 1234ms ou Android Bundled 987ms

Si vous voyez un écran rouge dans Expo Go, l'erreur est souvent une erreur d'exécution JavaScript. Ouvrez le terminal exécutant expo start pour lire la trace de la pile. Par exemple, Error: Cannot find module './screens/Home' signifie que le chemin du fichier est incorrect. Corrigez l'importation et l'application se recharge automatiquement.

Pour diagnostiquer les problèmes de réseau entre votre appareil et le serveur de développement, exécutez npx expo start --tunnel . Cela crée un tunnel qui fonctionne sur les réseaux restreints. La sortie attendue montre une nouvelle URL et un code QR. Si le tunnel échoue, installez @expo/ngrok globalement et réessayez.

Pour une vérification détaillée des dépendances, exécutez npx expo install --check . Cela compare les dépendances de votre package.json avec les versions recommandées pour votre SDK Expo. Si des incohérences sont trouvées, il les liste ; corrigez en exécutant npx expo install <paquet> pour chacune. Exemple de sortie :

The following packages should be updated: expo@49.0.0 -> 49.0.10

Exécutez npx expo install expo pour mettre à jour vers la version compatible.

## Modes d'échec et récupération

Chaque commande Expo peut échouer, et connaître les étapes de récupération fait gagner du temps. Modes d'échec courants et leurs correctifs :

Port déjà utilisé : L'exécution de npx expo start affiche Error: listen EADDRINUSE: address already in use :::8081 . Tuez le processus utilisant le port avec lsof -ti:8081 | xargs kill -9 (sur macOS/Linux) ou utilisez un port différent : npx expo start --port 8082 .

Corruption du cache Metro : Si le bundler se bloque ou ne parvient pas à résoudre les modules, videz le cache avec npx expo start -c . Cela redémarre Metro avec un cache propre. Sortie attendue : le bundler démarre et compile sans erreurs de modules obsolètes.

Incohérence de dépendance : Si expo start génère une erreur comme The package 'expo' is not installed in this project , exécutez npx expo install pour installer toutes les dépendances compatibles manquantes. Vérifiez avec npx expo-doctor .

Échec d'authentification avec EAS : L'exécution de eas build affiche Not logged in . Exécutez eas login avec votre compte Expo, puis vérifiez avec eas whoami (sortie attendue : votre nom d'utilisateur).

Échec de build dû à des secrets manquants : Si le build échoue avec Environment variable X is not set , ajoutez la variable dans le tableau de bord EAS sous Variables d'environnement, puis reconstruisez avec eas build -p android --profile preview --clear-cache .

Crash de l'application au démarrage : Si Expo Go affiche un écran d'erreur rouge, capturez le texte de l'erreur, recherchez la trace de la pile et corrigez l'erreur JavaScript. S'il s'agit d'un problème de module natif, vous devrez peut-être créer un build de développement avec npx expo run:android au lieu d'utiliser Expo Go.

Pour chaque échec, documentez l'erreur observée, la commande exécutée et l'étape qui l'a corrigée. Tenez un runbook personnel ou d'équipe avec ces entrées pour accélérer la récupération future.

## Liste de contrôle des opérations

Utilisez cette liste de contrôle avant et après chaque opération Expo pour garantir la cohérence et la sécurité.

Avant tout changement

- Vérifiez l'environnement : npx expo --version et npx expo-doctor . Assurez-vous que les deux passent.

- Sauvegardez la configuration : cp app.json app.json.bak .

- Identifiez la commande exacte et son résultat attendu.

- Vérifiez qu'aucun secret n'est codé en dur dans les fichiers à modifier.

Pendant l'opération

- Exécutez une commande à la fois.

- Capturez la sortie dans un journal : npx expo start > expo-start.log 2>&1 .

- Surveillez les signaux de succès attendus, tels que Metro waiting on http://localhost:8081 .

Après l'opération

- Vérifiez que l'application se charge sur la plateforme cible.

- Exécutez à nouveau npx expo-doctor pour confirmer l'absence de régressions.

- Si le changement a échoué, restaurez à partir de la sauvegarde : cp app.json.bak app.json .

- Documentez le résultat dans votre runbook.

Pour l'intégration CI/CD, créez des étapes de script :

# .gitlab-ci.yml exemple
expo-check:
 stage: test
 script:
 - npm install
 - npx expo-doctor
 - npx expo export --platform web --output-dir dist 
 Cela garantit que chaque demande de fusion passe les contrôles de santé Expo et peut produire un build web.

## Conclusion

Les commandes de base Expo ne deviennent des opérations sûres que lorsque vous les versionnez, observez avant de modifier et vérifiez chaque résultat. Une commande sans sa sortie attendue et son mode d'échec est une conjecture, pas une procédure. Utilisez l'inventaire de l'environnement pour établir une base de référence, démarrez et configurez les projets avec des sauvegardes, construisez avec des profils appropriés, diagnostiquez avec les journaux et récupérez avec des étapes documentées.

Commencez par une vérification à faible risque dans votre projet actuel : exécutez npx expo-doctor et npx expo start -c , enregistrez les sorties et confirmez que votre application se charge. Appliquez ensuite la même discipline à chaque build, mise à jour et changement de configuration. Le résultat est un flux de travail Expo reproductible qui rend les échecs visibles, protège les valeurs sensibles et permet à votre équipe de revenir plus rapidement à la construction de fonctionnalités.