Astro Integration

Add CometChat to an Astro app in 5 steps: create project, install, init, login, render.

AI Agent Component Spec

Field	Value
Package	@cometchat/chat-uikit-react
Peer deps	react >=18, react-dom >=18, @astrojs/react
Init	CometChatUIKit.init(UIKitSettings) — must resolve before login()
Login	CometChatUIKit.login("UID") — must resolve before rendering components
Order	init() → login() → render. Breaking this order = blank screen
Auth Key	Dev/testing only. Use Auth Token in production
SSR	CometChat requires browser APIs — use client:only="react" directive on Astro islands
CSS	import "@cometchat/chat-uikit-react/css-variables.css" in your React island
Calling	Optional. Install @cometchat/calls-sdk-javascript to enable
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.

CometChat UI Kit requires browser APIs (window, WebSocket, document). In Astro, always load CometChat components using the client:only="react" directive so they only render client-side.

---

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 (v16+) and npm/yarn installed.

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

---

Step 1 — Create an Astro Project

npm

npm create astro@latest my-app
cd my-app

pnpm

pnpm create astro@latest my-app
cd my-app

yarn

yarn create astro my-app
cd my-app

---

Step 2 — Add React and Install the UI Kit

First, add the React integration to Astro:

npx astro add react

This updates your astro.config.mjs automatically. Verify it includes:

astro.config.mjs

import { defineConfig } from "astro/config";
import react from "@astrojs/react";

export default defineConfig({
  integrations: [react()],
});

Then install the UI Kit:

npm

npm install @cometchat/chat-uikit-react

yarn

yarn add @cometchat/chat-uikit-react

This installs the UI Kit and its dependency @cometchat/chat-sdk-javascript automatically.

If you want voice/video calling, also install:

npm install @cometchat/calls-sdk-javascript

---

Step 3 — Initialize CometChat

In Astro, CometChat init and login happen inside your React island component (since they need browser APIs). Here’s the pattern:

import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";

/**
 * CometChat Constants - Replace with your actual credentials
 */
const COMETCHAT_CONSTANTS = {
  APP_ID: "APP_ID", // Replace with your actual App ID from CometChat
  REGION: "REGION", // Replace with your App's Region
  AUTH_KEY: "AUTH_KEY", // Replace with your Auth Key (leave blank if using Auth Token)
};

const UIKitSettings = new UIKitSettingsBuilder()
  .setAppId(COMETCHAT_CONSTANTS.APP_ID)
  .setRegion(COMETCHAT_CONSTANTS.REGION)
  .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
  .subscribePresenceForAllUsers()
  .build();

CometChatUIKit.init(UIKitSettings)
  .then(() => {
    console.log("CometChat UI Kit initialized successfully.");
  })
  .catch((error) => {
    console.error("CometChat UI Kit initialization failed:", error);
  });

init() must resolve before you call login(). If you call login() before init completes, it will fail silently.

---

Step 4 — Login

After init resolves, log the user in. 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

import { CometChatUIKit } from "@cometchat/chat-uikit-react";

const UID = "UID"; // Replace with your actual UID

CometChatUIKit.getLoggedinUser().then((user) => {
  if (!user) {
    CometChatUIKit.login(UID)
      .then((user) => {
        console.log("Login Successful:", { user });
        // Mount your app
      })
      .catch(console.log);
  } else {
    // Already logged in — mount your app
  }
});

Key points:

• getLoggedinUser() checks for an existing session so you don’t re-login unnecessarily.
• login(uid) skips the API call if a session already exists and returns the cached user.
• Components must not render until login resolves — use a state flag to gate rendering.

For production, use loginWithAuthToken() instead of Auth Key. Generate tokens server-side via the REST API.

---

Step 5 — Add the CSS Import

Import the CometChat CSS inside your React island component:

import "@cometchat/chat-uikit-react/css-variables.css";

Also ensure your global CSS sets height: 100% on the root elements. Create or update src/styles/globals.css:

src/styles/globals.css

html,
body {
  margin: 0;
  padding: 0;
  height: 100%;
}

Without the CSS import, components will render with broken or missing styles. Without the height rules, the chat UI won’t fill the viewport.

---

Step 6 — Choose a Chat Experience

Integrate a conversation view that suits your app’s UX. Each option below includes a step-by-step guide.

Conversation List + Message View

Two-panel layout — conversation list on the left, messages on the right. Think WhatsApp Web or Slack.

• Two-panel layout with conversation list and active chat window
• Switch between one-to-one and group conversations
• Tap-to-view on mobile — tapping a conversation opens the message view
• Real-time updates and message sync across sessions

Build Conversation List + Message View

Step-by-step guide to build this layout

---

One-to-One / Group Chat

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

• Dedicated chat window for one-on-one or group messaging
• No conversation list — users go directly into the chat
• Full-screen experience optimized for mobile
• Ideal for support chat or community messaging

Build One-to-One / Group Chat

Step-by-step guide to build this layout

---

Tab-Based Chat

Tabbed navigation — Chat, Call Logs, Users, Settings in separate tabs. Good for full-featured apps.

• Tab navigation between Chat, Call Logs, Users, and Settings
• Full-screen messaging within each tab
• Unified experience for conversations, call history, and settings
• Scales well for adding future features like notifications or contacts

Build Tab-Based Chat

Step-by-step guide to build this layout

---

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

Core Features

Chat features included out of the box

Troubleshooting

Common issues and fixes