Astro Integration - CometChat Docs

AI Integration Quick Reference

Field	Value
Package	`@cometchat/chat-uikit-react` v7.0.x
Peer deps	`react` >=18, `react-dom` >=18, `@cometchat/chat-sdk-javascript` ^4.1.9, `dompurify` ^3.3.1
Init	`CometChatUIKit.init(UIKitSettings)` — must resolve before `login()`
Login	`CometChatUIKit.login("UID")` — must resolve before rendering components
Order	`init()` → `login()` → render `<CometChatProvider>`. Breaking this order = blank screen
Auth Key	Dev/testing only. Use Auth Token in production
SSR	Use `client:only="react"` directive — CometChat components cannot be server-rendered
Calling	Optional. Install `@cometchat/calls-sdk-javascript` and call `.setCallingEnabled(true)` on `UIKitSettingsBuilder`
Other frameworks	React.js · Next.js · React Router

This guide walks you through adding CometChat to an Astro app using React islands. By the end you’ll have a working chat UI.

Prerequisites

You need three things from the CometChat Dashboard:

Credential	Where to find it
App ID	Dashboard → Your App → Credentials
Auth Key	Dashboard → Your App → Credentials
Region	Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`)

You also need Node.js 18+ and npm/yarn installed.

Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API. Never ship Auth Keys in client code.

Step 1 — Create an Astro Project

npm create astro@latest my-app
cd my-app
npx astro add react

When prompted by astro add react, confirm the installation of react, react-dom, and @astrojs/react.

Step 2 — Install the UI Kit

npm
yarn

npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify

yarn add @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript dompurify

If you want voice/video calling, also install:

npm install @cometchat/calls-sdk-javascript

Step 3 — Create the React Island Component

CometChat components live inside a React island (a .tsx file in src/components/). Initialize the SDK, login, then render inside CometChatProvider. For development, use one of the pre-created test UIDs: cometchat-uid-1 · cometchat-uid-2 · cometchat-uid-3 · cometchat-uid-4 · cometchat-uid-5

src/components/CometChatApp.tsx

import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatUIKit,
  UIKitSettingsBuilder,
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";

export default function CometChatApp() {
  const [ready, setReady] = useState(false);
  const [chatUser, setChatUser] = useState<CometChat.User | undefined>();
  const [chatGroup, setChatGroup] = useState<CometChat.Group | undefined>();

  useEffect(() => {
    const settings = new UIKitSettingsBuilder()
      .setAppId("YOUR_APP_ID")
      .setRegion("YOUR_REGION")
      .setAuthKey("YOUR_AUTH_KEY")
      .subscribePresenceForAllUsers()
      .build();

    CometChatUIKit.init(settings).then(async () => {
      await CometChatUIKit.login("cometchat-uid-1");
      setReady(true);
    });
  }, []);

  if (!ready) return <div>Loading chat...</div>;

  const handleConversationClick = (conversation: CometChat.Conversation) => {
    const entity = conversation.getConversationWith();
    if (conversation.getConversationType() === "user") {
      setChatUser(entity as CometChat.User);
      setChatGroup(undefined);
    } else {
      setChatGroup(entity as CometChat.Group);
      setChatUser(undefined);
    }
  };

  return (
    <CometChatProvider>
      <div style={{ display: "flex", height: "100vh" }}>
        <div style={{ width: 360, borderRight: "1px solid #eee" }}>
          <CometChatConversations onItemClick={handleConversationClick} />
        </div>
        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
          {(chatUser || chatGroup) && (
            <>
              <CometChatMessageHeader user={chatUser} group={chatGroup} />
              <CometChatMessageList user={chatUser} group={chatGroup} />
              <CometChatMessageComposer user={chatUser} group={chatGroup} />
            </>
          )}
        </div>
      </div>
    </CometChatProvider>
  );
}

CometChatProvider supplies theme, locale, plugin registry, and event context to all child components. Init and login happen in useEffect and the provider only mounts after login succeeds. See the CometChatProvider guide for all props.

For production, use CometChatUIKit.loginWithAuthToken(token) instead of login(uid). Generate auth tokens server-side via the CometChat REST API. Never ship auth keys in client code.

Step 4 — Render the Island in an Astro Page

Create an Astro page that renders the React island with client:only="react". This ensures the component only runs in the browser — no server-side rendering.

src/pages/index.astro

---
import CometChatApp from '../components/CometChatApp.tsx';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Chat App</title>
  </head>
  <body>
    <CometChatApp client:only="react" />
  </body>
</html>

You must use client:only="react" — not client:load or client:visible. CometChat components use browser APIs (DOM, WebSocket) and cannot be server-rendered. Using client:only skips SSR entirely.

Step 5 — Run

npm run dev

Open http://localhost:4321. You should see the conversation list on the left. Click a conversation to open the message panel.

Choose a Chat Experience

Conversation List + Message View

Two-panel layout — conversation list on the left, messages on the right.

One-to-One / Group Chat

Single chat window — no sidebar. Good for support chat or embedded widgets.

Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Settings in separate tabs.

Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

Sample App — Working reference app to compare against
Components — All prebuilt UI elements with props and customization options
Core Features — Messaging, real-time updates, and other capabilities
Theming — Colors, fonts, dark mode, and custom styling
Build Your Own UI — Skip the UI Kit entirely and build on the raw SDK

Next Steps

Components Overview

Browse all prebuilt UI components

Theming

Customize colors, fonts, and styles

Plugins

Customize message rendering

Troubleshooting

Common issues and fixes

​Prerequisites

​Step 1 — Create an Astro Project

​Step 2 — Install the UI Kit

​Step 3 — Create the React Island Component

​Step 4 — Render the Island in an Astro Page

​Step 5 — Run

​Choose a Chat Experience

​Conversation List + Message View

​One-to-One / Group Chat

​Tab-Based Chat

​Build Your Own Chat Experience

​Next Steps

Components Overview

Theming

Plugins

Troubleshooting

Prerequisites

Step 1 — Create an Astro Project

Step 2 — Install the UI Kit

Step 3 — Create the React Island Component

Step 4 — Render the Island in an Astro Page

Step 5 — Run

Choose a Chat Experience

Conversation List + Message View

One-to-One / Group Chat

Tab-Based Chat

Build Your Own Chat Experience

Next Steps