Claude Code et React Native : guide pratique Expo, natif et release

Fixer la limite mobile avant de demander du code

Claude Code est utile avec React Native parce qu’il ne se contente pas de produire un ecran. Il peut lire le projet, modifier TypeScript, lancer des commandes de verification, expliquer si une reconstruction native est necessaire et rendre une note de verification. C’est important, car le mobile traverse plus de frontieres qu’un composant web : permissions iOS, package Android, resolution Metro, development builds, emulateurs, accessibilite et controle de release.

La demande faible est “cree une app React Native”. La demande robuste dit si le projet est Expo, s’il exige un Expo development build, ou s’il s’agit d’un projet bare React Native ou l’equipe gere ios/ et android/. Elle precise aussi les fichiers modifiables, les commandes qui demandent validation et la plateforme a tester.

Les references officielles a garder sous la main sont Claude Code overview, Claude Code permissions, Expo documentation, Expo development builds, React Native environment setup, React Native Native Modules, Metro troubleshooting et React Native accessibility. Pour demarrer avec l’outil, lisez d’abord le guide de prise en main Claude Code puis le guide des permissions.

Commencer par un project map

Un project map est une courte notice d’exploitation pour l’agent. Le harness, autrement dit le cadre de travail de l’agent, indique a Claude Code ou il peut agir, comment verifier le resultat et quelles actions ne doivent pas etre automatiques. Sans cela, il peut produire du code valide mais oublier une reconstruction native, une divergence iOS/Android ou une contrainte de release.

flowchart LR
  A["Project map"] --> B["Claude Code task"]
  B --> C["JS/TS implementation"]
  B --> D["Native config"]
  C --> E["Metro and unit tests"]
  D --> F["Dev build / emulator"]
  E --> G["Accessibility check"]
  F --> G
  G --> H["Release checklist"]

Avant implementation, un fichier court suffit :

# React Native task map

App type: Expo app using TypeScript and Expo Router.
Native runtime: Expo Go for pure JS changes, development build for native libraries.
Targets: Android emulator first, iOS simulator on macOS before release.
Allowed files: app/, components/, hooks/, app.config.ts, metro.config.js, __tests__/.
Do not change: package manager, app slug, bundle identifiers, signing files, .env files.
Verification: npm run lint, npm test, npx expo-doctor, Android emulator smoke test.
Handoff: list changed files, commands run, platform not tested, and any native rebuild needed.

Les modeles Expo recents peuvent inclure du contexte pour les agents de code. Dans une application existante, il reste pourtant courant de trouver un ancien README, des hypotheses d’ancien SDK et des reglages natifs non documentes. Faites lire le depot reel avant toute modification.

Choisir Expo ou bare React Native volontairement

La documentation React Native distingue le developpement avec framework du chemin ou Android Studio et Xcode sont configures directement. En pratique, Expo est souvent le plus rapide pour une nouvelle app. Bare React Native reste pertinent avec des SDK natifs existants, Gradle complexe, Pods personnalises ou contraintes fournisseur.

Decision	Expo convient mieux	Bare React Native convient mieux
Demarrage	MVP, outils internes, apprentissage, fonctions couvertes par Expo SDK	Code iOS/Android existant a conserver
Fonctions natives	Camera, SecureStore, notifications et reglages via config plugins	SDK proprietaire, terminal de paiement, Bluetooth specifique, build tres personnalise
Portee Claude Code	app/, components/, app.config.ts, tests	ios/, android/, Codegen, Pods, Gradle, artefacts generes
Verification	Expo Go ou development build, npx expo-doctor	npm run android, pod install, builds Xcode/Android Studio

Expo Go ne prouve pas qu’un release build fonctionnera. Expo le decrit comme un environnement rapide avec un ensemble fixe de bibliotheques natives. Si vous ajoutez une dependance avec code natif, utilisez un development build et demandez a Claude Code de signaler qu’un nouveau binaire est requis.

Pour un projet Expo propre :

npx create-expo-app@latest rn-claude-lab
cd rn-claude-lab
npx expo install expo-camera expo-secure-store @react-native-community/netinfo
npm install --save-dev @testing-library/react-native jest-expo @types/jest
npx expo start

Appuyez sur a pour Android Emulator ou i pour iOS Simulator sur macOS. Si le reseau bloque le terminal, npx expo start --tunnel peut aider, mais le flux sera plus lent.

Regler les permissions Claude Code pour le mobile

Dans React Native, une seule commande peut produire un grand diff. expo prebuild, pod install, gradlew clean et eas build sont utiles au bon moment, mais ils ne doivent pas partir silencieusement pendant une petite modification UI.

Les permissions Claude Code se separent en allow, ask et deny. Un .claude/settings.json partage peut autoriser les verifications sures, demander validation avant regeneration native ou build release, et bloquer secrets et publication.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npx expo-doctor)",
      "Bash(adb devices)"
    ],
    "ask": [
      "Edit",
      "Bash(npx expo prebuild*)",
      "Bash(eas build*)",
      "Bash(cd ios && bundle exec pod install)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.local)",
      "Bash(git push*)",
      "Bash(rm -rf*)"
    ]
  }
}

Le but n’est pas de se mefier de l’outil. Le but est de garder les effets de bord mobiles dans une unite revisable. Si une reconstruction native est necessaire, Claude Code doit l’annoncer avant d’elargir le diff.

Implementer un ecran avec permission camera

Premier cas concret : un lecteur QR pour check-in, inventaire ou outil interne. Expo Camera expose CameraView et useCameraPermissions. Demandez a Claude Code de separer trois etats : permission en cours de chargement, permission non accordee, camera prete. Ajoutez aussi labels accessibles et protection contre les lectures multiples.

// components/CameraQrCheck.tsx
import { CameraView, useCameraPermissions } from 'expo-camera';
import { useState } from 'react';
import { Pressable, StyleSheet, Text, View } from 'react-native';

type ScanResult = {
  data: string;
  type: string;
} | null;

export function CameraQrCheck() {
  const [permission, requestPermission] = useCameraPermissions();
  const [scan, setScan] = useState<ScanResult>(null);

  if (!permission) {
    return (
      <View style={styles.center}>
        <Text>Checking camera permission...</Text>
      </View>
    );
  }

  if (!permission.granted) {
    return (
      <View style={styles.center}>
        <Text style={styles.title}>Camera access is required</Text>
        <Text style={styles.body}>
          Allow camera access to scan QR codes on this device.
        </Text>
        <Pressable
          accessibilityRole="button"
          accessibilityLabel="Allow camera access"
          disabled={!permission.canAskAgain}
          onPress={requestPermission}
          style={({ pressed }) => [
            styles.button,
            pressed && styles.buttonPressed,
            !permission.canAskAgain && styles.buttonDisabled,
          ]}
        >
          <Text style={styles.buttonText}>Allow camera</Text>
        </Pressable>
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <CameraView
        style={styles.camera}
        barcodeScannerSettings={{ barcodeTypes: ['qr'] }}
        onBarcodeScanned={
          scan
            ? undefined
            : ({ data, type }) => {
                setScan({ data, type });
              }
        }
      />
      <View style={styles.result}>
        <Text accessibilityLiveRegion="polite" style={styles.title}>
          {scan ? `Scanned ${scan.type}` : 'Point the camera at a QR code'}
        </Text>
        {scan ? <Text selectable>{scan.data}</Text> : null}
        {scan ? (
          <Pressable
            accessibilityRole="button"
            accessibilityLabel="Scan another QR code"
            onPress={() => setScan(null)}
            style={styles.button}
          >
            <Text style={styles.buttonText}>Scan again</Text>
          </Pressable>
        ) : null}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: '#111827' },
  center: { flex: 1, justifyContent: 'center', gap: 12, padding: 24 },
  camera: { flex: 1 },
  result: { gap: 12, padding: 16, backgroundColor: '#f9fafb' },
  title: { fontSize: 18, fontWeight: '700', color: '#111827' },
  body: { fontSize: 15, lineHeight: 22, color: '#374151' },
  button: {
    alignItems: 'center',
    borderRadius: 8,
    backgroundColor: '#2563eb',
    paddingHorizontal: 16,
    paddingVertical: 12,
  },
  buttonPressed: { opacity: 0.75 },
  buttonDisabled: { backgroundColor: '#9ca3af' },
  buttonText: { color: '#ffffff', fontWeight: '700' },
});

Ce composant est copiable dans un projet Expo apres installation de expo-camera. Les textes de permission et la configuration native doivent rester dans app config, car certains changements demandent une reconstruction native.

// app.config.ts
import type { ConfigContext, ExpoConfig } from 'expo/config';

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: config.name ?? 'rn-claude-lab',
  slug: config.slug ?? 'rn-claude-lab',
  ios: {
    ...config.ios,
    bundleIdentifier: 'com.example.rnclaudelab',
    infoPlist: {
      ...config.ios?.infoPlist,
      NSCameraUsageDescription: 'Scan QR codes for check-in.',
    },
  },
  android: {
    ...config.android,
    package: 'com.example.rnclaudelab',
    permissions: ['CAMERA'],
  },
  plugins: ['expo-camera'],
});

Les config plugins Expo appliquent ces reglages pendant prebuild et les builds natifs. La consigne utile est simple : “si tu modifies app.config.ts, indique si un development build est necessaire”.

Traiter les erreurs Metro comme des preuves

Deuxieme cas : Unable to resolve module, surtout en monorepo. La page officielle Metro mentionne le reset de cache, mais ce n’est pas une analyse de cause racine.

Donnez a Claude Code l’erreur complete, la commande, le package manager, la structure workspace et le dernier deplacement de fichier. Une app Expo dans un workspace peut necessiter :

// metro.config.js
const path = require('path');
const { getDefaultConfig } = require('expo/metro-config');

const projectRoot = __dirname;
const workspaceRoot = path.resolve(projectRoot, '..');

const config = getDefaultConfig(projectRoot);

config.watchFolders = [workspaceRoot];
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(workspaceRoot, 'node_modules'),
];

module.exports = config;

Ne l’ajoutez pas automatiquement. Une app Expo simple n’en a souvent pas besoin. Demandez a Claude Code d’expliquer pourquoi watchFolders est necessaire et de l’eviter si le probleme vient de la casse, d’une dependance manquante, de Babel ou d’un import.

Planifier les modules natifs avant de modifier le natif

Troisieme cas : connecter un SDK fournisseur ou une API systeme. Le guide actuel Native Modules met l’accent sur Turbo Native Modules et Codegen. Une bonne tache commence donc par l’interface TypeScript, puis seulement par Android et iOS.

Si Camera, SecureStore ou NetInfo d’Expo suffisent, n’ecrivez pas de module natif maison. Pour un terminal de paiement, un Bluetooth specifique ou un SDK interne, demandez d’abord un plan.

Implement a native bridge plan, not the full code yet.

Goal: expose a device serial reader to TypeScript.
First output:
1. TypeScript interface and error model.
2. Android/iOS files that would need edits.
3. Build commands for each platform.
4. Risks: permissions, threading, simulator limitations, release signing.
Do not edit ios/ or android/ until the plan is reviewed.

Cela ralentit un peu le debut mais accelere la revue. Kotlin, Swift, Pods et Gradle ont un cout de verification eleve.

Mettre tests et accessibilite dans la meme tache

Les API d’accessibilite React Native alimentent VoiceOver et TalkBack. Si une vue doit etre accessible, son label et son role font partie de l’implementation.

Commencez par tester l’etat sans permission :

// __tests__/CameraQrCheck.test.tsx
import React from 'react';
import { fireEvent, render, screen } from '@testing-library/react-native';
import { CameraQrCheck } from '../components/CameraQrCheck';

const mockRequestPermission = jest.fn();

jest.mock('expo-camera', () => ({
  CameraView: 'CameraView',
  useCameraPermissions: () => [
    { granted: false, canAskAgain: true },
    mockRequestPermission,
  ],
}));

describe('CameraQrCheck', () => {
  beforeEach(() => {
    mockRequestPermission.mockClear();
  });

  it('requests camera permission from the empty state', () => {
    render(<CameraQrCheck />);

    fireEvent.press(screen.getByText('Allow camera'));

    expect(mockRequestPermission).toHaveBeenCalledTimes(1);
  });
});

Puis verifiez sur appareil ou emulateur : dialogue de permission, refus, rotation, scan en faible lumiere et libelles lecteur d’ecran. Le handoff doit dire quelle plateforme a ete testee. “Android emulator passed, iOS not tested” est utile ; “looks good” ne l’est pas.

Transformer le release check en commandes

Dev Menu et LogBox sont des outils de developpement ; les builds release se comportent differemment. Claude Code doit rendre des preuves de commandes.

npm run lint
npm test -- --runInBand
npx expo-doctor
npx expo start -c
adb devices
adb shell input keyevent 82
npx expo run:android
# macOS only:
npx expo run:ios

Avec EAS Build, separez les profils development, preview et production. Ne laissez pas Claude Code changer bundle identifier, Android package, signing files ou profil production sans demande explicite.

Cas d’usage et echecs frequents

Premier cas : un nouveau MVP Expo. Login, QR scan, stockage local securise, API simple et workflow interne peuvent etre separes en screens, hooks, tests et config. Si l’app a un objectif commercial, ajoutez analytics et CTA aux criteres de fin.

Deuxieme cas : corriger une app bare existante. Erreurs Metro, crash Android uniquement, texte de permission iOS et upgrade SDK natif sont de bonnes taches si vous exigez classification d’erreur, diff minimal et note sur la reconstruction native.

Troisieme cas : recherche avant integration SDK natif. Paiement, sante, Bluetooth et authentification entreprise meritent un tableau avec OS supportes, permissions, risque de store review, limites simulateur et appareils de test. Utilisez aussi le review workflow checklist et le guide TDD.

Les pieges sont recurrents : Expo Go ne prouve pas le release, reset cache n’est pas une cause racine, la verification iOS/Android ne doit pas attendre la fin, l’accessibilite ne se colle pas apres coup, et les commandes natives ont besoin d’une raison.

CTA : transformer le flux en modele

En React Native, le plus rentable est de reutiliser project map, permissions, commandes de verification et checklist de revue. Pour travailler seul, commencez avec la cheatsheet gratuite. Pour des prompts et supports de configuration, consultez les produits ClaudeCodeLab. Pour appliquer des regles Expo/bare React Native, CI, release gates et formation a un vrai depot, utilisez Claude Code training and consultation.

Comparez aussi avec le guide React avec Claude Code et le guide Flutter/Dart.

Apres avoir teste ce flux, Masa a constate que trois habitudes reduisent le plus les retours : choisir Expo ou bare avant d’implementer, demander une note development build quand app.config.ts change, et verifier permissions et Metro d’abord sur Android Emulator. Pour Camera et SecureStore, la frontiere de verification compte plus que la vitesse de generation.