cometchat-react-native-expo-patterns

Ground truth: @cometchat/chat-uikit-react-native@5 + catalog rn-v5.json. Docs: /ui-kit/react-native/expo-integration · expo-conversation · expo-tab-based-chat.

Companion skills (read first)

• cometchat-react-native-core — install, provider chain, init→login→render. Assumed, not repeated here.
• cometchat-react-native-bare-patterns — the bare React Native CLI equivalent. Use that one, not this, for a non-Expo app.

Use this skill when

• the project has app.json/app.config.js with an expo key, or expo in package.json
• "add chat to my Expo app" · "chat isn't working in Expo Go"

Prerequisites & install

⚠️ Expo Go does not work — and this is the #1 support issue

The UI Kit ships custom native modules. Expo Go is a fixed prebuilt binary that cannot load them. There is no workaround, no config flag, and nothing to fix in code. You need a development build.

Symptom: the app runs in Expo Go but chat screens crash or render nothing, with a NativeModule error that names gesture-handler / svg / video rather than CometChat — so it reads as unrelated.

npx expo run:ios      # or: npx expo run:android

Both produce a development build. From then on use that build, not Expo Go.

Packages

Same list as bare RN, plus punycode, which is Expo-only:

npm install @cometchat/chat-uikit-react-native@5 @cometchat/chat-sdk-react-native@4
npm install @react-native-clipboard/clipboard \
  react-native-svg react-native-video react-native-localize react-native-gesture-handler \
  react-native-safe-area-context @react-native-async-storage/async-storage@^2.1.2 dayjs punycode

Native config lives in app.json — never in ios/ or android/

This is the whole Expo/bare divergence: Expo generates the native projects, so hand-editing Info.plist or AndroidManifest.xml is pointless — the next prebuild overwrites it. Declare permissions in app.json and let Expo write them:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSCameraUsageDescription": "Camera access for video calls",
        "NSMicrophoneUsageDescription": "Microphone access for voice/video calls"
      }
    },
    "android": {
      "permissions": [
        "android.permission.INTERNET",
        "android.permission.CAMERA",
        "android.permission.MODIFY_AUDIO_SETTINGS",
        "android.permission.RECORD_AUDIO",
        "android.permission.ACCESS_NETWORK_STATE",
        "android.permission.BLUETOOTH_CONNECT",
        "android.permission.VIBRATE"
      ]
    }
  }
}

• BLUETOOTH_CONNECT (Android 12+) lets calls route audio to a Bluetooth headset — /calls/react-native/setup lists it; the calls SDK's own manifest only merges the legacy BLUETOOTH.
• No READ_/WRITE_EXTERNAL_STORAGE, though the expo-integration page lists them: they are no-ops on modern Android (WRITE from 11, READ from 13), and the UI Kit's own manifest already merges them for older devices.