Clerk Expo (React Native)

Implémentez Clerk dans les projets Expo / React Native. Cette compétence intègre des patterns vérifiés pour la surface stable (provider, cache de tokens, flows) et requiert une inspection du code source du package @clerk/expo installé pour tout ce qui est volatil (props des composants, signatures des hooks).

Règles d'activation

Activez quand l'une des conditions est vraie :

L'utilisateur demande l'authentification dans une app Expo ou React Native, ou mentionne @clerk/expo, ClerkProvider, Expo Router auth, ou des hooks Clerk dans une app native.
Le projet est Expo/React Native (app.json / app.config.js, expo dans package.json, metro.config.js, dépendance @clerk/expo).

Redirigez quand :

Projet iOS/Swift natif (.xcodeproj, Package.swift) → clerk-swift
Projet Android/Kotlin natif (build.gradle sans React Native) → clerk-android
Framework web uniquement (Next.js, Remix, React pur, etc.) → la compétence du framework correspondant

Carte des intentions

Associez ce que l'utilisateur a demandé, puis chargez les références listées. Chargez uniquement ce dont la tâche a besoin.

Intention de l'utilisateur (exemples)	Chemin	Référence
« Ajouter l'auth à mon app » / « ajouter la connexion avec Clerk »	Composants natifs préconstruits (défaut)	references/setup.md + references/prebuilt-components.md
« Ajouter l'auth » mais Expo Go / web / UI personnalisée requise	Flows personnalisés	references/setup.md + references/custom-flows.md
« Ajouter l'auth par téléphone / SMS », « OTP email », « passwordless »	Flow personnalisé, `phoneCode` / `emailCode`	references/custom-flows.md
« Connexion avec Google/Apple/GitHub », « social login », « SSO »	SSO navigateur ou boutons natifs	references/sso-and-native-auth.md
« MFA / 2FA / TOTP », « mot de passe oublié », « lien email »	Ajouts au flow personnalisé	references/custom-flows.md
« Protéger les routes/écrans », « redirection si déconnecté »	Gardes Expo Router	references/protected-routes.md
« Afficher le profil utilisateur », « changement d'org », « notifications push », « déconnexion », « appeler mon backend »	Recettes d'app	references/recipes.md
« Connexion biométrique », « Face ID », « passkeys »	Fonctionnalités de l'appareil	references/recipes.md

Décision du chemin par défaut

Quand l'utilisateur dit « ajouter l'auth » sans préciser l'UI :

Défaut aux composants natifs préconstruits (AuthView + UserButton de @clerk/expo/native). L'authentification la plus rapide à mettre en place ; l'UI est maintenue par Clerk. Dites au développeur qu'ils sont en bêta et qu'un build de développement est requis.
Retombez aux flows personnalisés quand l'une de ces conditions est vraie — dites pourquoi quand vous basculez :
- Le projet doit s'exécuter dans Expo Go (pas de build de développement).
- L'app cible le web (les composants natifs ne s'affichent pas sur le web).
- Le développeur veut sa propre UI ou une expérience de marque spécifique au-delà de la thématisation.
Si le développeur a une UI d'authentification existante, étendez ce qui s'y trouve — ne déchirez pas les flows personnalisés pour insérer AuthView (ou vice versa) sans être demandé.

Ne mélangez pas composants préconstruits et flows personnalisés pour la même étape d'authentification (ex. AuthView plus un formulaire de mot de passe personnalisé). Le mélange est autorisé seulement quand le développeur le demande explicitement.

Flux de travail rapide

Confirmez le type de projet (Expo/RN) et choisissez le chemin selon les règles Intent Map / Default Path.
Suivez references/setup.md : installation, clé env, provider, cache de tokens, plugin de config, type de build.
Vérifiez les prérequis du dashboard (Gate 2 et Gate 3 ci-dessous).
Implémentez à partir de la référence sélectionnée uniquement.
Vérifiez en buildant, pas seulement en écrivant :
- Exécutez la vérification des types du projet (npx tsc --noEmit ou équivalent).
- Build et lancement : npx expo run:ios / run:android pour les fonctionnalités natives, npx expo start pour les flows Expo Go. Si le build échoue, corrigez et rebuildez itérativement — les erreurs de build contre le SDK installé sont la vérité première quand cette compétence et le SDK divergent. Après ~5 tentatives de correction échouées, arrêtez et demandez au développeur comment procéder plutôt que de continuer en tâtonnant.
- Guidez le développeur à travers une vraie connexion, puis confirmez que la session survit à un redémarrage de l'app (cache de tokens fonctionnant).

Portes d'exécution (Ne pas sauter)

Clé publiable — Lisez depuis process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY (fichier .env). Jamais NEXT_PUBLIC_, jamais en dur. Si aucune clé n'existe, demandez-en une au développeur (ou exécutez npx clerk@latest init --framework expo, qui installe le SDK et écrit le fichier env) et attendez avant d'éditer les fichiers.
Basculement du dashboard Native API — L'API Native de Clerk doit être activée pour l'instance : Clerk Dashboard → Native applications (https://dashboard.clerk.com/~/native-applications). Dites au développeur de vérifier ceci lors de la configuration ; c'est obligatoire pour toute intégration native.
Disponibilité des facteurs — Avant d'implémenter une stratégie spécifique (SMS, code email, provider social), confirmez qu'elle est activée pour l'instance. Dérivez l'URL de l'API Frontend à partir de la clé publiable (base64-décodez le segment du milieu) et récupérez <frontendApiUrl>/v1/environment?_is_native=true, ou demandez au développeur de vérifier le dashboard (User & authentication). SMS en particulier dépend de la configuration de l'instance — le code écrit pour un facteur désactivé échoue à l'exécution, pas à la compilation.
Seulement l'API custom-flows courante — useSignIn() / useSignUp() depuis @clerk/expo (v3.4+) retournent { signIn, errors, fetchStatus } et utilisent des flows basés sur les méthodes : signIn.password(), signIn.phoneCode.sendCode(), signIn.finalize(). Ne générez jamais le pattern legacy : destructurer isLoaded/setActive depuis useSignIn()/useSignUp() (les hooks courants ne les retournent pas), ou signIn.create() enchaîné avec prepareFirstFactor()/attemptFirstFactor() + setActive({ session }). Ce pattern vit à @clerk/expo/legacy et est seulement pour maintenir le code legacy existant, jamais pour du nouveau travail. Remarques de scope : isLoaded depuis useAuth()/useUser() est l'API courante et requis dans les gardes ; signIn.create() lui-même existe toujours pour les cas avancés — préférez les méthodes spécifiques aux facteurs.
useSSO(), jamais useOAuth() — useOAuth est deprecated. Notez l'asymétrie : startSSOFlow() retourne toujours { createdSessionId, setActive } et requiert setActive({ session: createdSessionId }) — SSO n'utilise pas finalize().
Cache de tokens — tokenCache depuis @clerk/expo/token-cache sur ClerkProvider. N'utilisez jamais expo-secure-store directement pour les tokens de session, jamais AsyncStorage.
resourceCache, jamais secureStore — si la mise en cache de ressources hors ligne arrive à la surface, @clerk/expo/secure-store est deprecated ; utilisez resourceCache depuis @clerk/expo/resource-cache.
Gating par type de build — Les composants natifs (@clerk/expo/native) et les hooks natifs (useSignInWithGoogle, useSignInWithApple, useLocalCredentials) requièrent un build de développement (npx expo run:ios / run:android), pas Expo Go, et n'existent pas sur le web. Pour les cibles web, utilisez les composants @clerk/expo/web ou des flows personnalisés. Énoncez l'exigence du build avant d'implémenter une fonctionnalité native uniquement.
Défaut de connexion-ou-inscription combinée — un flow combiné à moins que le développeur demande des écrans de connexion et d'inscription séparés.
Protection bot — les écrans d'inscription personnalisés doivent afficher <View nativeID="clerk-captcha" /> ; la protection bot de Clerk est activée par défaut et a besoin de ce point de montage.
Vérification de source pour les surfaces volatiles — avant d'utiliser les props des composants natifs ou les options des hooks natifs, confirmez contre le package installé : node_modules/@clerk/expo/dist/native/*.d.ts et package.json exports. La version installée prime sur cette compétence si elles divergent.
Porte de fraîcheur — cette compétence a été vérifiée contre @clerk/expo 3.6.x. Vérifiez la version installée (node_modules/@clerk/expo/package.json). Si c'est une mineure plus récente ou une majeure, traitez les extraits de code de cette compétence avec méfiance : re-vérifiez contre l'URL de docs citée à côté de chaque extrait (chaque section de référence en porte une) ou le .d.ts installé avant de les utiliser. Si c'est plus ancien que 3.4, l'API des flows personnalisés basée sur les méthodes peut ne pas exister — proposez une mise à niveau au lieu d'écrire du code legacy.

Notes de version (v3.5–v3.6, juin 2026)

React Native minimum passé à 0.75 en v3.5.0 (iOS SDK se lie maintenant via podspec SPM). Gamme de pairs : expo >=53 <57.
Composants natifs mûrs : iOS passé à Expo Modules ; la synchro de session native↔JS est automatique et bidirectionnelle — n'appelez jamais setActive() après l'authentification du composant natif.
Le plugin de config accepte un fichier theme JSON pour la stylisation des composants natifs (voir references/prebuilt-components.md).
La connexion native Google migrera vers un package séparé @clerk/expo-google-signin en majeure suivante (l'import @clerk/expo/google continue de fonctionner en v3 ; un avertissement dev annonce la migration). Ne pré-installez pas le nouveau package en v3.

Pièges courants

Niveau	Problème	Prévention
CRITIQUE	Génération de code custom-flow legacy (`signIn.create` + `prepareFirstFactor` + `setActive`)	Utilisez l'API courante basée sur les méthodes (Gate 4)
CRITIQUE	Utilisation de `useOAuth()`	Utilisez `useSSO()` (Gate 5)
CRITIQUE	Implémentation d'auth SMS/social sans vérifier que le facteur est activé	Vérifiez d'abord l'environnement/dashboard (Gate 3)
CRITIQUE	Composants natifs ciblés à Expo Go ou web	Exigez un build de développement ; proposez des flows personnalisés autrement (Gate 8)
CRITIQUE	Écran d'inscription manquant `<View nativeID="clerk-captcha" />`	Incluez-le toujours (Gate 10)
HAUTE	Préfixe env `NEXT_PUBLIC_`, ou variable env lue dans `node_modules`	`EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, passée explicitement à `ClerkProvider`
HAUTE	Session perdue au redémarrage	`tokenCache` depuis `@clerk/expo/token-cache` sur le provider
HAUTE	Appel de `setActive()` après l'auth `AuthView` / `UserButton`	Les composants natifs synchro les sessions automatiquement
HAUTE	Appairage de `AuthView` avec `useSignInWithGoogle`/`useSignInWithApple`	`AuthView` affiche les providers sociaux activés lui-même
HAUTE	Appel manuel de `WebBrowser.maybeCompleteAuthSession()`	`ClerkProvider` le gère
HAUTE	Division connexion / inscription sans être demandé	Flow combiné par défaut (Gate 9)
MOYEN	Vérification manquante de `isLoaded` avant `isSignedIn` dans les gardes	Toujours gater sur `isLoaded` d'abord
MOYEN	Utilisation de `yalc`/`pnpm link` pour le développement local de `@clerk/expo`	Utilisez Verdaccio ou pkg.pr.new

Voir aussi

clerk — routeur de haut niveau
clerk-swift / clerk-android — SDKs mobiles natifs
clerk-orgs, clerk-billing, clerk-webhooks — compétences de fonctionnalités (les hooks fonctionnent de la même façon dans Expo)
Source du package installé : node_modules/@clerk/expo/
https://clerk.com/docs/getting-started/quickstart (onglet Expo SDK)
https://clerk.com/docs/reference/expo/overview
https://github.com/clerk/clerk-expo-quickstart — trois apps d'exemple officielles : JS uniquement (Expo Go), JS + boutons natifs de connexion, composants natifs