Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

cometchat-native-core

Shared rules for CometChat React Native UI Kit v5. Always loaded alongside framework (expo/bare) and placement skills. Read this first.

cometchat · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add cometchat/cometchat-skills --skill cometchat-native-core

About this skill


name: cometchat-native-core description: "Shared rules for CometChat React Native UI Kit v5. Always loaded alongside framework (expo/bare) and placement skills. Read this first." license: "MIT" compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5; @cometchat/chat-sdk-react-native ^4" allowed-tools: "executeBash, readFile, fileSearch, listDirectory" metadata: author: "CometChat" version: "3.0.0" tags: "chat cometchat react-native core rules initialization provider theming"

Purpose

This is the foundational skill for every CometChat React Native UI Kit v5 integration. It teaches Claude HOW CometChat works on RN — initialization order, provider wrapper chain, login, env vars, auth tokens, and the anti-patterns that break real apps.

Read this skill first, before any framework (cometchat-native-expo-patterns / cometchat-native-bare-patterns) or placement skill.

Ground-truth sources: docs/ui-kit/react-native/overview.mdx, react-native-cli-integration.mdx, expo-integration.mdx, methods.mdx, and @cometchat/chat-uikit-react-native@5.3.3's src/index.ts.


1. The init-login-render order

CometChat has exactly one valid lifecycle on React Native:

CometChatUIKit.init(settings)   →   CometChatUIKit.login({ uid })   →   render <CometChat*> components

Breaking this order produces a blank screen, a "CometChat is not initialized" runtime error, or a hung login. No exceptions.

UIKitSettings — the init object

import {
  CometChatUIKit,
  UIKitSettingsBuilder,
} from "@cometchat/chat-uikit-react-native";

const settings = new UIKitSettingsBuilder()
  .setAppId(APP_ID)         // Required — from the CometChat dashboard
  .setRegion(REGION)         // Required — "us" | "eu" | "in"
  .setAuthKey(AUTH_KEY)      // Required for dev mode. Omit in production.
  .subscribePresenceForAllUsers()  // Optional but recommended — online indicators
  .build();

await CometChatUIKit.init(settings);

Init must happen once

Use a module-level flag to prevent double-init. React re-mounts in dev (strict mode, fast refresh, and navigation nesting all trigger effect re-fires):

let initialized = false;

async function initCometChat(): Promise<void> {
  if (initialized) return;
  initialized = true;

  const settings = new UIKitSettingsBuilder()
    .setAppId(APP_ID)
    .setRegion(REGION)
    .setAuthKey(AUTH_KEY)
    .subscribePresenceForAllUsers()
    .build();

  await CometChatUIKit.init(settings);
}

Init must run before first render

Put the init call in a top-level useEffect (preferred — the provider pattern in section 6 does this) or in App.tsx before the initial navigator mounts. Avoid calling init() in a screen's effect — by the time the screen mounts, the app has already tried to render components that expect init to be done.


2. Login

Development mode

const user = await CometChatUIKit.getLoggedinUser();
if (!user) {
  await CometChatUIKit.login({ uid: "cometchat-uid-1" });  // note: OBJECT form
}

⚠️ login() takes an object { uid: "..." } on React Native, not a bare string like on the web. Passing "cometchat-uid-1" directly silently fails.

Every new CometChat app ships 5 pre-seeded test users — cometchat-uid-1 through cometchat-uid-5. Use one for development.

⚠️ login() is safe sequentially, NOT concurrently

A second login() call fired while the first is in-flight throws "Please wait until the previous login request ends." Classic trap in React Native because:

  • React strict mode double-mounts effects
  • react-navigation remounts screens on tab switches
  • Fast Refresh triggers effect re-runs in dev

Guard with a module-level in-flight promise, same pattern as the web skill:

let loginInFlight: Promise<unknown> | null = null;

async function ensureLoggedIn(uid: string, authToken?: string): Promise<void> {
  const existing = await CometChatUIKit.getLoggedinUser();
  if (existing) return;
  if (loginInFlight) {
    await loginInFlight;   // reuse the pending promise
    return;
  }
  loginInFlight = authToken
    ? CometChatUIKit.login({ authToken })
    : CometChatUIKit.login({ uid });
  try {
    await loginInFlight;
  } finally {
    loginInFlight = null;
  }
}

Call ensureLoggedIn() from the provider / effect. Both mounts resolve against the same promise; only one login request hits the server.

Production mode

Use CometChatUIKit.login({ authToken }) with a token from your backend. The backend generates the token with the CometChat REST API using the server-only REST API Key (not the client-side Auth Key). See cometchat-native-production for the server-side token endpoint patterns.

Logout

await CometChatUIKit.logout();

Clears the local CometChat session. Call from your app's sign-out handler.


3. Provider wrapper chain (mandatory order)

Every CometChat RN app has this wrapper chain at the root. Missing wrappers cause silent layout breakage, broken gestures, or hard crashes — each wrapper is required by a specific RN ecosystem piece the UI Kit depends on.

// App.tsx (bare) or the root of your Expo app
import "react-native-gesture-handler";   // MUST be the first import
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <SafeAreaProvider>
        <CometChatThemeProvider>
          <CometChatProvider>    {/* your own init/login provider — see section 6 */}
            <AppNavigator />
          </CometChatProvider>
        </CometChatThemeProvider>
      </SafeAreaProvider>
    </GestureHandlerRootView>
  );
}

Why each wrapper is mandatory:

WrapperRequired because
`import "react-native-gestur
Read the complete source ↗