Configuration d'un laboratoire local React Native : guide pratique avec exemples

Introduction

Une configuration de laboratoire local React Native avec des exemples pratiques vous aide à passer d'un problème observé à un résultat vérifié. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des variables fictives au lieu de secrets, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint.

Ce guide s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui ont besoin d'un environnement local fiable et reproductible. Il couvre l'inventaire des versions et de l'environnement, les chemins de configuration sûrs, la vérification et les diagnostics, les modes de défaillance et la récupération, ainsi qu'une liste de contrôle opérationnelle finale. Chaque section inclut des commandes, les résultats attendus, les signaux d'échec et les décisions de récupération pour la configuration, les tests, les exemples et le développement de React Native.

Avant de commencer, assurez-vous que votre poste de travail répond aux prérequis suivants :

• Node.js version 18 ou supérieure (vérifiez avec node --version)
• npm version 9 ou supérieure (vérifiez avec npm --version)
• Watchman installé et en cours d'exécution (requis sur macOS et Linux pour la surveillance des fichiers)
• Un éditeur de code tel que Visual Studio Code
• Un émulateur d'appareil (AVD d'Android Studio ou simulateur Apple) ou un appareil physique avec le débogage activé

Tout au long de cet article, les commandes utilisent des variables fictives comme <app-name> ou <device-id>. Remplacez-les par vos propres valeurs. Ne mettez jamais de véritables identifiants, jetons, clés privées ou identifiants de production dans les fichiers de configuration ou les commandes.

Inventaire des versions et de l'environnement

Avant de faire des modifications, identifiez la version installée, la topologie de déploiement, les prérequis et le composant exact que vous inspectez. Cette section vous aide à capturer l'état actuel afin que toute modification ultérieure soit limitée et réversible.

Commencez par confirmer les versions de la chaîne d'outils de base. Ouvrez un terminal et exécutez :

node --version
npm --version
npx react-native --version

Le résultat attendu sur un système sain ressemble à ceci :

v18.18.2
9.8.1
13.6.4

Si une commande échoue ou renvoie une version plus ancienne, ne procédez pas à la configuration du projet. Mettez d'abord à niveau le composant manquant. Pour Node.js, utilisez un gestionnaire de versions tel que nvm :

nvm install 18
nvm use 18

Pour npm, exécutez npm install -g npm@9 en tant qu'administrateur ou utilisateur disposant d'un accès en écriture au répertoire npm global.

Ensuite, vérifiez si la CLI React Native est installée globalement ou localement. L'approche recommandée est d'utiliser npx pour exécuter la CLI depuis le node_modules de votre projet, ce qui évite les conflits de version. Exécutez npx react-native --version dans le répertoire de votre projet ; il devrait renvoyer la version spécifiée dans le package.json du projet.

Si vous prévoyez d'utiliser Expo pour le prototypage, vérifiez la version de la CLI Expo séparément :

npx expo --version

Exemple de résultat attendu : 6.3.10. Notez qu'Expo et React Native bare ont des chemins de commande et des fichiers de configuration différents. Gardez-les séparés ; ne mélangez pas les flux de travail dans le même projet sauf si vous utilisez intentionnellement Expo prebuild.

Enregistrez les versions dans un fichier lab-environment.txt ou une feuille de variables d'environnement dédiée. Cela facilite la comparaison avec une machine propre ou la configuration d'un collègue.

Chemin de configuration sûr

Les modifications de configuration sont la source la plus courante de laboratoires locaux cassés. Le principe clé : faites une modification limitée à la fois, connaissez son rayon d'impact et vérifiez le résultat avant de continuer. Gardez toujours une copie de la configuration d'origine afin de pouvoir revenir rapidement en arrière.

Initialisation du projet

Créez un nouveau projet React Native en utilisant la CLI communautaire :

npx @react-native-community/cli init MyLabApp --version 0.73.4

Cette commande crée un nouveau répertoire MyLabApp avec la version spécifiée de React Native. Si vous omettez --version, la CLI installe la dernière version stable, ce qui peut varier d'une machine à l'autre. Épinglez la version dans votre projet pour plus de cohérence.

Après l'initialisation, naviguez dans le projet et démarrez le bundler Metro dans un terminal séparé :

cd MyLabApp
npx react-native start

Laissez Metro en cours d'exécution. Dans un deuxième terminal, exécutez l'application sur un émulateur :

npx react-native run-android

Le résultat attendu inclut des lignes telles que :

BUILD SUCCESSFUL
Installing APK 'app-debug.apk' on 'Pixel_5_API_33(AVD)'
Starting: Intent { cmp=com.mylabapp/.MainActivity }

Si vous utilisez iOS, exécutez npx react-native run-ios --simulator="iPhone 15" et recherchez BUILD SUCCEEDED .

Modification des fichiers de configuration

Supposons que vous deviez changer le nom d'affichage de l'application. Dans android/app/src/main/res/values/strings.xml, localisez :

<string name="app_name">MyLabApp</string>

Changez-le en :

<string name="app_name">My Lab App</string>

Rayon d'impact : affecte uniquement le libellé de l'application Android, pas le bundle ID, le nom du package ou le code JavaScript. Rebuildez avec npx react-native run-android et confirmez que l'émulateur affiche le nouveau nom.

Si le changement n'apparaît pas, videz le cache de build :

cd android
./gradlew clean
cd ..
npx react-native run-android

C'est une opération plus lourde car elle force une reconstruction complète, donc utilisez-la uniquement lorsqu'un build incrémental échoue.

Pour iOS, le nom d'affichage se trouve dans ios/MyLabApp/Info.plist sous la clé CFBundleDisplayName. Changez la valeur et relancez npx react-native run-ios.

Enregistrez toujours les valeurs avant et après dans vos notes de laboratoire. Ainsi, si l'application se comporte de manière inattendue plus tard, vous pourrez identifier quelle configuration a changé et quand.

Vérification et diagnostics

La vérification doit être automatique et reproductible. Construisez un petit ensemble de contrôles qui confirment que le laboratoire fonctionne de bout en bout : le bundler est en cours d'exécution, l'application s'installe, JavaScript s'exécute et les modules natifs se chargent.

Script de test de fumée

Créez un fichier scripts/verify-lab.sh avec le contenu suivant :

#!/usr/bin/env bash
set -euo pipefail

echo "Checking Node.js version >= 18"
node --version | grep -E '^v(1[8-9]|[2-9][0-9])\.' || { echo "Node.js too old"; exit 1; }

echo "Checking npm version >= 9"
npm --version | grep -E '^(9|1[0-9])\.' || { echo "npm too old"; exit 1; }

echo "Checking Metro bundler is responding"
curl -s http://localhost:8081/status | grep -q 'packager-status:running' || { echo "Metro not running"; exit 1; }

echo "All checks passed"

Rendez-le exécutable et exécutez-le :

chmod +x scripts/verify-lab.sh
./scripts/verify-lab.sh

Résultat attendu :

Checking Node.js version >= 18
Checking npm version >= 9
Checking Metro bundler is responding
All checks passed

Si Metro n'est pas en cours d'exécution, le script se termine avec Metro not running. Démarrez Metro avec npx react-native start dans un terminal séparé et relancez le script.

Diagnostic des échecs de build

Lorsque npx react-native run-android échoue, localisez d'abord la ligne d'erreur dans la sortie Gradle. Les motifs courants incluent :

• SDK location not found -> ouvrez android/local.properties et assurez-vous que sdk.dir pointe vers le chemin de votre SDK Android, par exemple /Users/yourname/Library/Android/sdk.
• Could not resolve com.facebook.react:react-native:0.73.4 -> vérifiez vos android/build.gradle et android/app/build.gradle pour la version correcte de React Native ; synchronisez le projet ou exécutez cd android && ./gradlew --refresh-dependencies.
• Execution failed for task ':app:processDebugMainManifest' -> souvent causé par un AndroidManifest.xml mal formé. Passez en revue les derniers changements et exécutez ./gradlew processDebugMainManifest --stacktrace pour plus de détails.

Pour iOS, exécutez npx react-native run-ios --verbose pour voir les étapes de build détaillées. Les problèmes courants incluent les dépendances CocoaPods manquantes (exécutez cd ios && pod install) ou les erreurs de signature de code (définissez temporairement la signature sur automatique dans Xcode, mais ne commitez jamais d'identités de signature personnelles).

Liste de contrôle de diagnostic

Gardez cette liste de contrôle dans votre documentation de laboratoire et exécutez-la après chaque modification de configuration :

• [ ] node --version renvoie v18 ou plus
• [ ] npm --version renvoie 9 ou plus
• [ ] npx react-native --version correspond au package.json du projet
• [ ] Le bundler Metro répond sur http://localhost:8081/status
• [ ] L'émulateur ou l'appareil est reconnu (adb devices sur Android affiche device, xcrun simctl list devices sur iOS affiche un appareil Booted)
• [ ] npx react-native run-android (ou run-ios) se termine sans erreur
• [ ] L'application se lance et affiche l'écran par défaut

Modes de défaillance et récupération

Même avec une configuration soignée, les laboratoires locaux se cassent. Cette section décrit les modes de défaillance les plus fréquents, comment les reconnaître et les chemins de récupération étape par étape.

Mode de défaillance 1 : Conflit de port du bundler Metro

Symptôme : Le démarrage de Metro échoue avec Error: listen EADDRINUSE: address already in use :::8081.

Cause : Un autre processus (peut-être une ancienne instance de Metro ou un autre outil) utilise déjà le port 8081.

Récupération : Trouvez le processus et tuez-le :

lsof -i :8081
# Notez le PID, puis :
kill -9 <PID>

Sinon, démarrez Metro sur un port différent :

npx react-native start --port 8082

Ensuite, exécutez l'application avec npx react-native run-android --port 8082. Vérifiez en ouvrant http://localhost:8082/status dans un navigateur.

Mode de défaillance 2 : Émulateur Android introuvable

Symptôme : npx react-native run-android signale No connected devices ou emulator not found.

Cause : L'émulateur Android n'est pas installé, l'AVD n'est pas créé, ou la variable d'environnement ANDROID_HOME est manquante.

Récupération :

1. Vérifiez ANDROID_HOME :

echo $ANDROID_HOME

S'il est vide, ajoutez-le à ~/.bashrc ou ~/.zshrc :

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

1. Listez les AVD disponibles :

emulator -list-avds

S'il n'existe aucun AVD, créez-en un à l'aide du Device Manager d'Android Studio ou de la ligne de commande :

avdmanager create avd -n Pixel_5_API_33 -k "system-images;android-33;google_apis;x86_64"

1. Démarrez l'émulateur et relancez l'application.

Mode de défaillance 3 : Le build iOS échoue avec CocoaPods could not find compatible versions

Symptôme : pod install échoue avec une erreur de conflit de version.

Cause : Le Podfile.lock n'est pas synchronisé avec le Podfile actuel, ou une dépendance nécessite une version plus récente de CocoaPods.

Récupération :

• Mettez à jour CocoaPods : sudo gem install cocoapods
• Supprimez Podfile.lock et le dossier Pods, puis exécutez pod install --repo-update.
• Si le conflit persiste, vérifiez l'exigence de version spécifique du pod dans Podfile et ajustez-la, ou utilisez pod update <PodName> pour mettre à jour uniquement ce pod.

Mode de défaillance 4 : Fast Refresh ne fonctionne pas

Symptôme : Les modifications du code JavaScript n'apparaissent pas dans l'application même après l'enregistrement.

Cause : Le bundler Metro a perdu la connexion WebSocket avec l'application, ou l'application a été buildée en mode release.

Récupération :

• Assurez-vous que l'application est en mode debug (pas en release).
• Secouez l'appareil ou appuyez sur Cmd+M (Android) / Cmd+D (iOS) dans l'émulateur et sélectionnez « Reload ».
• Si Fast Refresh est désactivé, activez-le dans le menu du développeur.
• Redémarrez Metro et réinstallez l'application : npx react-native run-android (ou run-ios).

Documentez toujours les étapes de récupération que vous avez utilisées et leur efficacité. Cela constitue un runbook pour votre équipe et réduit les temps d'arrêt lors d'incidents futurs.

Pièges courants et comment les éviter

Les pièges sont des erreurs que même les développeurs expérimentés commettent parce qu'elles semblent inoffensives au premier abord. Voici les plus fréquents dans les configurations de laboratoire local React Native et comment les contourner.

Piège 1 : Mélanger les CLI globales et locales

Pourquoi cela arrive : Les développeurs installent react-native-cli globalement pour plus de commodité, puis exécutent des commandes react-native depuis un projet qui attend une version différente.

Comment l'éviter : Utilisez toujours npx react-native ou le binaire local du projet dans node_modules/.bin/react-native. Vérifiez avec which react-native pour voir quel binaire est utilisé. Si une version globale existe, supprimez-la : npm uninstall -g react-native-cli.

Piège 2 : Coder en dur des chemins absolus dans la configuration

Pourquoi cela arrive : Définir sdk.dir ou d'autres chemins vers un chemin absolu spécifique à la machine, souvent copié depuis la configuration d'un collègue.

Comment l'éviter : Utilisez des variables d'environnement et gardez les valeurs spécifiques à la machine hors du contrôle de version. Pour le SDK Android, utilisez local.properties (qui est gitignoré par défaut) et référencez $ANDROID_HOME dans les scripts de build. Pour les autres chemins, utilisez des références relatives ou l'expansion ~.

Piège 3 : Exécuter des commandes depuis le mauvais répertoire

Pourquoi cela arrive : Exécuter npx react-native run-android depuis un répertoire parent qui ne contient pas le projet React Native, ce qui conduit à des erreurs déroutantes.

Comment l'éviter : Confirmez toujours votre répertoire de travail avec pwd et assurez-vous qu'il contient package.json avec les dépendances React Native. Utilisez des invites de terminal ou un script pour vérifier le répertoire avant d'exécuter des commandes.

Piège 4 : Ignorer la discordance d'architecture de l'émulateur

Pourquoi cela arrive : Sur les Mac Apple Silicon, l'émulateur Android peut nécessiter une image système ARM64 ; installer une image x86_64 peut entraîner des performances lentes ou un échec de démarrage.

Comment l'éviter : Vérifiez l'architecture de votre machine (uname -m). Si c'est arm64, installez des images système Android compatibles ARM via le SDK Manager ou sdkmanager "system-images;android-33;google_apis;arm64-v8a".

Piège 5 : Committer les fichiers natifs générés

Pourquoi cela arrive : Les nouveaux développeurs peuvent committer les dossiers android/ et ios/ générés par la CLI, mais avec le temps, ces dossiers accumulent des caches et dépendances spécifiques à la machine.

Comment l'éviter : Utilisez un .gitignore qui exclut android/build, android/app/build, ios/Pods et local.properties. Si votre équipe utilise Expo prebuild, envisagez de committer les dossiers natifs générés uniquement après un examen minutieux, ou utilisez une étape CI pour les générer.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle chaque fois que vous commencez à travailler dans votre laboratoire, après toute modification de configuration et avant d'exécuter une suite de tests ou une démonstration. Chaque élément inclut un responsable et une fréquence de révision pour les environnements d'équipe.

Le responsable est une seule personne imputable, pas un groupe. Si la vérification échoue, le responsable décide de corriger immédiatement ou d'escalader. Les fréquences de révision garantissent que le laboratoire reste sain même lorsque les membres de l'équipe changent.

Conclusion

Une configuration de laboratoire local React Native avec des exemples pratiques n'est utile que si chaque recommandation est limitée à la version, observable et réversible là où la technologie le permet. Copier une commande sans vérifier les prérequis et les résultats attendus n'est pas une procédure d'exploitation.

Commencez par une vérification à faible risque : exécutez npx react-native --version et comparez-le au package.json de votre projet. Enregistrez l'état actuel, puis exécutez le script de vérification de ce guide. Si une vérification échoue, utilisez la section sur les modes de défaillance et la récupération pour le résoudre avant de faire d'autres modifications. Ne révisez les dépendances telles qu'Expo, Android et les intégrations d'API REST qu'après que le laboratoire de base est stable.

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 récupération avant qu'un incident ne force la décision. Construisez votre laboratoire avec ces principes, et vous passerez moins de temps à déboguer et plus de temps à livrer.