Enable Offline Support - CometChat Docs

AI Integration Quick Reference

Field	Value
Package	`@cometchat/chat-sdk-react-native` (4.2.0 or later)
Config class	`CometChat.OfflineConfig` — `new CometChat.OfflineConfig({ enabled: true })`
Attach to	`new CometChat.AppSettingsBuilder().setOfflineConfig(config)` (or the `.offline(true)` shorthand)
Install (peers)	`@op-engineering/op-sqlite` 9.0.0+ (required), `react-native-fs`, `react-native-keychain`
Verify	`CometChat.isOfflineEnabled()` → `boolean`
Constraints	Off by default. Not available in Expo Go — use a development build or `expo prebuild`.

const offlineConfig = new CometChat.OfflineConfig({ enabled: true });

const appSettings = new CometChat.AppSettingsBuilder()
  .setRegion("REGION")
  .setOfflineConfig(offlineConfig) // explicit config; its `enabled` wins
  // .offline(true)                // shorthand: enable with all defaults
  .build();

await CometChat.init("APP_ID", appSettings);

const active: boolean = CometChat.isOfflineEnabled();

Offline support is off by default. You turn it on once, at initialization, by attaching an OfflineConfig to your AppSettings. Until you do, the SDK behaves exactly as before: no local store is opened and no native module is loaded. This page covers the minimal setup; for every tunable option see the Configuration & API Reference.

Requirements

Offline support requires CometChat React Native Chat SDK 4.2.0 or later.The local database is provided by a native module that you install in your app. It is an optional peer dependency of the SDK, so installing the SDK never requires it:

Package	Needed for
`@op-engineering/op-sqlite` (9.0.0 or later)	The local store. Required for offline. Without it the SDK runs online-only.
`react-native-fs`	Media caching and durable media sends.
`react-native-keychain`	Storing the encryption key, only with encryption.

npm install @op-engineering/op-sqlite react-native-fs

@op-engineering/op-sqlite is a native module. In Expo, use a development build or expo prebuild — offline does not run in Expo Go (the SDK then runs online-only). Pick an op-sqlite release that supports your React Native version.

If you are new to the SDK, complete the standard setup first; the steps below only add offline configuration to your existing init.

Build an OfflineConfig

Construct an OfflineConfig and set enabled: true. Every other option has a sensible default, so set only what you need. Invalid values are normalised to the default; they are never rejected.

TypeScript
JavaScript

const offlineConfig: CometChat.OfflineConfig = new CometChat.OfflineConfig({
  enabled: true,
});

const offlineConfig = new CometChat.OfflineConfig({
  enabled: true,
});

Attach it to AppSettings

Pass the config to AppSettingsBuilder.setOfflineConfig(...). To enable with all defaults instead of building a config, use the offline(boolean) shorthand.

TypeScript
JavaScript

const appSettings: CometChat.AppSettings = new CometChat.AppSettingsBuilder()
  .setRegion("REGION")
  .setOfflineConfig(offlineConfig) // explicit config
  // .offline(true)                // shorthand: enable with defaults
  .build();

const appSettings = new CometChat.AppSettingsBuilder()
  .setRegion("REGION")
  .setOfflineConfig(offlineConfig) // explicit config
  // .offline(true)                // shorthand: enable with defaults
  .build();

If you call both setOfflineConfig(...) and offline(boolean), the explicit OfflineConfig wins — its enabled value is authoritative.

Initialize the SDK

Pass the settings to CometChat.init(...) as you do today. No other call changes.

TypeScript
JavaScript

CometChat.init("APP_ID", appSettings).then(
  () => {
    console.log("Initialization completed successfully");
  },
  (error: CometChat.CometChatException) => {
    console.log("Initialization failed with error:", error);
  }
);

CometChat.init("APP_ID", appSettings).then(
  () => {
    console.log("Initialization completed successfully");
  },
  (error) => {
    console.log("Initialization failed with error:", error);
  }
);

On a relaunch with a saved login, init also starts offline support, and waits for it for up to 8 seconds. Add your cache-reset and outbox listeners straight after await CometChat.init(...) resolves. Anything raised during startup is delivered just after init resolves.

Verify it is active

Call CometChat.isOfflineEnabled(). It returns true only while offline support is actually active for the logged-in user. It is false before anyone logs in (even when you enabled it in AppSettings), after logout or session expiry, and when the local store or the encryption key store cannot open. Read it at the moment of each decision and keep no copy of the result.

TypeScript
JavaScript

const active: boolean = CometChat.isOfflineEnabled();
console.log("Offline support active:", active);

const active = CometChat.isOfflineEnabled();
console.log("Offline support active:", active);

Next steps

Offline support is now active for the logged-in user. Continue with Show Cached Data to adopt the two-phase listeners, and Send While Offline for the durable outbox. Tune caps, TTLs, media, and encryption from the Configuration & API Reference.

​Next steps

Next steps