[raj-dubey1]

Description

Adds Offline Support docs for the React Native SDK (v4) and React Native UI Kit (v5). The JavaScript SDK, React and Angular docs are in a separate PR (#566).

Do not merge yet. The RN SDK offline work is PR cometchat-team/chat-sdk-react-native#440 (shipping as 4.2.0, with the parity fixes from rajdubey/eng-40403-offlinern-sdk-parity-with-android-sdk-production-ready-fixes). The RN UI Kit work is cometchat-team/uikit-react-native#1434. Both are open and unreleased, so these pages must not go live until they ship. The SDK version (4.2.0) is filled in; fill in the minimum UI Kit version (the {/* TODO */} note on the UI Kit page) before merging.

Files

File	Change
sdk/react-native/offline-support.mdx	New page (SDK 4.2.0): requirements (op-sqlite 9.0.0+, react-native-fs, react-native-keychain, React Native 0.74+, Expo dev build / EAS, no Expo Go), enable with CometChat.OfflineConfig, all 14 config options, isOfflineEnabled, two-phase reads, queued sends (queued vs failed), pending messages, failure reasons and retry, sync listener, other offline methods (reference table), encryption (SQLCipher, react-native-keychain, setOfflineKeyVault, encryptionFailureBehavior), cache resets, login / logout, limitations
ui-kit/react-native/offline-support.mdx	New page: dependencies (NetInfo required), the offline field on UIKitSettings and chatSDK.offline for initFromSettings, what changes in the components (incl. pending / failed indicators)
ui-kit/react-native/core-features.mdx	New "Offline Support" section, and a link in the quick reference
docs.json	Nav: RN SDK → Messaging (after Reactions). RN UI Kit → Features → Chat (after Core). No redirect added: the existing /ui-kit/react-native/5.0/:slug* wildcard already covers the new page, and SDK pages get no redirects when they are new
sdk/react-native/llms-react-native-v4.mdx, ui-kit/react-native/llms-react-native-v5.mdx	LLM index entries

Verified against source

• RN SDK 4.2.0: branch rajdubey/eng-40403-offlinern-sdk-parity-with-android-sdk-production-ready-fixes @ a935639f (CHANGELOG.md 4.2.0 entry, docs/offline/SETUP.md, docs/offline/ANDROID_PARITY.md, src/lib/offline/**, src/lib/CometChat.ts, dist/CometChat.d.ts). Earlier revisions were checked against PR Updated Integration Guide #440 head 18460a41.
  • Config: OFFLINE_CONFIG_DEFAULTS (enabled: false, also in the fromJson / settings-file object form), normalizeCount ranges, maxSnapshotQueries / snapshotTtlDays <= 0 → default. prefetch* keys are removed in 4.2.0 and not documented.
  • Queued send: onMessagePending (status PENDING, getLocalMessageId() set), then one onError(error, null) with errorParams.queued === true, code FAILED_TO_FETCH; the Promise rejects with it (OfflineErrors.queuedNotConnectedError, OfflineSends.sendMessage). The ERROR_OFFLINE_MESSAGE_QUEUED text is gone.
  • Failures (Outbox.ts, FailureClassifier.ts): 5xx / 429 and the 5-reconnect no-answer cap (ERROR_OUTBOX_AUTO_FLUSH_CAP_REACHED) → TRANSIENT; other rejections → PERMANENT; admission → ERROR_PENDING_QUEUE_LIMIT with QUEUE_FULL / QUEUE_OVERFLOW / BYTE_OVERFLOW; clearOfflineCache() / conversation purge → DISCARDED. retryMessage accepts FAILED only (ERROR_OFFLINE_MESSAGE_NOT_RETRYABLE otherwise); retryAllFailedMessages retries TRANSIENT only; nothing auto-retries FAILED. The cap counts PENDING + SENDING, not FAILED. Send answer timeout 15 s / 120 s media.
  • Methods: getMediaCachingMode() (getMediaCaching() deprecated, OFF while offline is inactive); getLastSyncTimestamp() server seconds; getCacheSize() includes media; forceSyncNow cooldown 10 s (FORCE_SYNC_COOLDOWN_MS); onMessageSyncCompleted(messages, outcome); addOfflineCacheResetListener + OfflineCacheResetReason; setOfflineKeyVault (public, documented in the SDK's own setup notes; OfflineKeyStore removed); getOfflineEncryptionStatus() cipher = SQLCipher version, leakage always set.
  • Lifecycle (ANDROID_PARITY L5–L8): same-uid re-login keeps cache and outbox; logout, token expiry, a different uid and a failed login wipe.
  • Two-phase reads: the cache phase always fires (empty for a server-only filter) while offline is running.
• RN UI Kit at b0d236f, plus the companion 4.2.0 compatibility change in progress (removes the automatic retry of FAILED messages, treats DISCARDED as final, uses getMediaCachingMode(), treats a queued send as pending). packages/ChatUiKit/package.json on the PR branch is still 5.5.1, so the UI Kit version stays TODO. UIKitSettings.offline?: boolean | object; CometChatUIKit.init passes it through OfflineConfig.fromJson; initFromSettings passes chatSDK.offline to the SDK. CometChatMessageList.tsx imports @react-native-community/netinfo at the top level (the bundle fails without it). Pending / failed indicators: MessageUtils.tsx and CometChatConversations.tsx (WAIT / ERROR receipts).
• Hands-on tests (Android emulator, bare RN and Expo, on the pre-4.2.0 SDK): no op-sqlite or Expo Go → offline silently off; airplane-mode send → queued, getPendingMessages() shows PENDING, onMessageSent once on reconnect; SQLCipher build → getOfflineEncryptionStatus() reports atRest: "SQLCIPHER". The 4.2.0 send-notice change has not been re-run on a device.

Release blockers and points for reviewers

Versions to fill in: the minimum RN UI Kit version (TODO comment on the UI Kit page). The RN SDK version is 4.2.0.

Resolved by SDK 4.2.0 (the pages now document the fixed behaviour): onMessagePending status / getLocalMessageId(); fromJson enabled default; queued sends now notify through onError (no MESSAGE_QUEUED); getMediaCachingMode(); DISCARDED reason and callbacks on clearOfflineCache(); OfflineKeyStore removed (setOfflineKeyVault documented); SyncOutcome at runtime; maxSnapshotQueries / snapshotTtlDays 0 handling.

Still open:

1. RN UI Kit: the companion change must land in #1434 before release — remove the automatic retry of FAILED messages on reconnect (now that localMessageId is set and FAILED is retryable, the NetInfo backstop in CometChatMessageList would auto-resend failed messages), treat DISCARDED as final, switch to getMediaCachingMode(), and keep a queued send (errorParams.queued) as pending. The UI Kit page already describes that behaviour.
2. RN UI Kit imports @react-native-community/netinfo without declaring it, so any app upgrading the kit fails to bundle, even with offline off (the page lists it as required).
3. The reconnect catch-up of edits / deletes / reactions needs a server-side changelog feature; the SDK page has a deliberately vague note about it. Confirm it is live on all regions before release, or keep the note.
4. SDK d.ts doc comments still say the no-answer cap fails PERMANENT (MessageFailureReason.PERMANENT, OfflineErrorCode.AUTO_FLUSH_CAP_REACHED); the code and CHANGELOG say TRANSIENT, and the docs follow the code. ERROR_PENDING_QUEUE_LIMIT is not exposed on CometChat.OfflineErrorCode, so the docs use the string.

Decision for the author: the original scope rule (document only what all five SDKs share) left out retry, forceSyncNow, clearOfflineCache, getSyncState, getLastSyncTimestamp, getCacheSize and the media APIs because they are stubs on iOS. This revision documents them on the RN page because they exist and work in the RN SDK. Revert those sections if the cross-platform rule should win.

Checks

• docs.json parses, and every new nav entry resolves to a file.
• Every internal link and anchor in the changed files resolves.
• review-docs-pr analyzer (--scope sdk/react-native/ and --scope ui-kit/react-native/): no missing redirects, no unresolved nav refs, no broken links in the PR's files (3 pre-existing broken links in untouched RN SDK pages; the llms-* files are intentionally outside the nav).
• The three changed pages compile with @mdx-js/mdx 3 + GFM. npx mint broken-links (as of 5bedd98) now stops at the pre-existing parse error in ui-kit/react/integration-astro.mdx, which this PR doesn't touch; it stops the same way on d705439 today (an earlier mint run on d705439 reported "no broken links found").

Type of Change

• New documentation

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Oct 20, 2026, 9:11 AM

💡 Tip: Enable Automations to automatically generate PRs for you.