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 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add cometchat/cometchat-skills --skill cometchat-native-core技能说明
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-navigationremounts 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:
| Wrapper | Required because |
|---|---|
| `import "react-native-gestur |