> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Install, import, and initialize the CometChat JavaScript SDK in your web app.

<Note>
  Migrating app version from v3 to v4 ?

  Skip the create new app step. Your existing v3 app can be migrated to v4.

  Follow steps mentioned in **Add the CometChat dependency** section below to upgrade to latest version of v4
</Note>

## Get your Application Keys

[Signup for CometChat](https://app.cometchat.com) and then:

1. Create a new app
2. Head over to the **API & Auth Keys** section and note the **Auth Key**, **App ID** & **Region**

## Add the CometChat Dependency

### NPM

<Tabs>
  <Tab title="JavaScript">
    ```js theme={null}
    npm install @cometchat/chat-sdk-javascript
    ```

    Then import wherever needed:

    ```javascript theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";
    ```

    ### CDN

    ```html theme={null}
    <script
      type="text/javascript"
      src="https://unpkg.com/@cometchat/chat-sdk-javascript/CometChat.js"
    ></script>
    ```

    When using the CDN, `CometChat` is available as a global variable.
  </Tab>
</Tabs>

## Initialization

The `init()` method initializes the SDK and must be called before any other CometChat method. Call it once at app startup, typically in your entry file (`index.js`, `main.js`, or `App.js`).

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    let appID: string = "APP_ID";
    let region: string = "APP_REGION";

    let appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder()
    .subscribePresenceForAllUsers()
    .setRegion(region)
    .autoEstablishSocketConnection(true)
    .build();

    CometChat.init(appID, appSetting).then(
    (initialized: boolean) => {
    console.log("Initialization completed successfully", initialized);
    },
    (error: CometChat.CometChatException) => {
    console.log("Initialization failed with error:", error);
    }
    );

    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    let appID = "APP_ID";
    let region = "APP_REGION";

    let appSetting = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(region)
      .autoEstablishSocketConnection(true)
      .build();

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

    Alternatively, you can use the `async/await` syntax:

    ```javascript theme={null}
    let appID = "APP_ID";
    let region = "APP_REGION";

    let appSetting = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(region)
      .autoEstablishSocketConnection(true)
      .build();

    try {
      await CometChat.init(appID, appSetting);
      console.log("Initialization completed successfully");
    } catch (error) {
      console.log("Initialization failed with error:", error);
    }
    ```
  </Tab>
</Tabs>

Replace `APP_ID` and `APP_REGION` with your credentials from the [Dashboard](https://app.cometchat.com).

<Warning>
  `CometChat.init()` must be called before any other SDK method. Calling
  `login()`, `sendMessage()`, or registering listeners before `init()` will
  fail.
</Warning>

### Parameters

| Parameter  | Type        | Description                                        |
| ---------- | ----------- | -------------------------------------------------- |
| appID      | string      | Your CometChat App ID                              |
| appSetting | AppSettings | Configuration object built with AppSettingsBuilder |

### AppSettings Options

| Method                                | Description                                                              | Default  |
| ------------------------------------- | ------------------------------------------------------------------------ | -------- |
| `setRegion(region)`                   | Region where your app was created (`us`, `eu`, `in`)                     | Required |
| `subscribePresenceForAllUsers()`      | Subscribe to presence events for all users                               | —        |
| `subscribePresenceForRoles(roles)`    | Subscribe to presence for specific roles                                 | —        |
| `subscribePresenceForFriends()`       | Subscribe to presence for friends only                                   | —        |
| `autoEstablishSocketConnection(bool)` | Let SDK manage WebSocket connections                                     | `true`   |
| `overrideAdminHost(adminHost)`        | Custom admin URL (dedicated deployment)                                  | —        |
| `overrideClientHost(clientHost)`      | Custom client URL (dedicated deployment)                                 | —        |
| `setStorageMode(storageMode)`         | Local storage mode (`CometChat.StorageMode.SESSION` for session storage) | —        |

### Presence Subscription

Choose how to subscribe to user presence (online/offline status):

```javascript theme={null}
// All users
new CometChat.AppSettingsBuilder()
  .subscribePresenceForAllUsers()
  .setRegion(region)
  .build();

// Specific roles
new CometChat.AppSettingsBuilder()
  .subscribePresenceForRoles(["admin", "moderator"])
  .setRegion(region)
  .build();

// Friends only
new CometChat.AppSettingsBuilder()
  .subscribePresenceForFriends()
  .setRegion(region)
  .build();
```

See [User Presence](/sdk/javascript/user-presence) for more details.

### WebSocket Connection

By default, the SDK manages WebSocket connections automatically. To manage them manually:

```javascript theme={null}
let appSetting = new CometChat.AppSettingsBuilder()
  .setRegion(region)
  .autoEstablishSocketConnection(false)
  .build();
```

See [Managing WebSocket Connections](/sdk/javascript/managing-web-sockets-connections-manually) for manual control.

### Session Storage

Use session storage instead of local storage (data clears when browser closes):

```javascript theme={null}
let appSetting = new CometChat.AppSettingsBuilder()
  .setRegion(region)
  .setStorageMode(CometChat.StorageMode.SESSION)
  .build();
```

## SSR Compatibility

The CometChat SDK requires browser APIs (`window`, `WebSocket`) and cannot run on the server. For SSR frameworks, initialize the SDK only on the client side.

<Tabs>
  <Tab title="Next.js">
    Import the SDK dynamically in `useEffect`:

    ```javascript theme={null}
    import React from "react";

    export default function Home() {
      let [ready, setReady] = React.useState(false);

      React.useEffect(() => {
        window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat;
        setReady(true);
      }, []);

      return ready ? <Chat /> : <p>Loading...</p>;
    }
    ```
  </Tab>

  <Tab title="NuxtJS">
    Import the SDK in the `mounted` lifecycle hook:

    ```javascript theme={null}
    export default {
      data() {
        return { ready: false };
      },
      mounted() {
        window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat;
        this.ready = true;
      }
    };
    ```
  </Tab>

  <Tab title="Ionic/Cordova">
    Use the JavaScript SDK directly. Import and initialize in your root component:

    ```typescript theme={null}
    import { CometChat } from "@cometchat/chat-sdk-javascript";

    ngOnInit() {
      const appSetting = new CometChat.AppSettingsBuilder()
        .subscribePresenceForAllUsers()
        .setRegion("APP_REGION")
        .autoEstablishSocketConnection(true)
        .build();

      CometChat.init("APP_ID", appSetting).then(
        () => console.log("CometChat initialized successfully"),
        (error) => console.log("CometChat initialization failed:", error)
      );
    }
    ```

    <Note>
      The dedicated Ionic Cordova SDK has been deprecated. For new Ionic/Cordova
      applications, use the JavaScript SDK as shown above.
    </Note>
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/sdk/javascript/authentication-overview">
    Log in users with Auth Key or Auth Token
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/javascript/send-message">
    Send your first message
  </Card>
</CardGroup>