Getting Started With CometChat React UI Kit in Astro

Step-by-step guide to integrate CometChat React UI Kit into your Astro application using @astrojs/react islands.

AI Agent Component Spec

• Package: @cometchat/chat-uikit-react — npm install @cometchat/chat-uikit-react + npx astro add react
• Required setup: CometChatUIKit.init(UIKitSettings) then CometChatUIKit.login("UID") — must complete before rendering
• SSR: CometChat requires browser APIs — use client:only="react" directive on Astro islands
• Init code: new UIKitSettingsBuilder().setAppId("APP_ID").setRegion("REGION").setAuthKey("AUTH_KEY").build()
• Framework: Astro (this page) | React.js | Next.js | React Router
• All components: Components Overview

The CometChat UI Kit for React provides prebuilt UI components for in-app chat. In Astro, integrate via the @astrojs/react integration to get themeable chat UI with client:only="react" islands.

Prerequisites

Create a CometChat application via the CometChat Dashboard. The dashboard provides user management, group chat, voice/video calling, and real-time notifications.

Required credentials from the dashboard:

1. App ID
2. Auth Key
3. Region

Getting Started

1. Create an Astro Project

   npm

   npm create astro@latest
   cd <my-astro-app>
   npm install
   

   pnpm

   pnpm create astro@latest my-astro-app --template basics
   cd <my-astro-app>
   pnpm install
   

   yarn

   yarn create astro my-astro-app --template basics
   cd <my-astro-app>
   yarn
   

   CometChat UI and SDK must run on the client. Use client:only="react" for Astro islands.

2. Install Dependencies

   Install CometChat UI Kit

   npm i @cometchat/chat-uikit-react
   

   Add React to Astro

   npx astro add react
   

   Ensure the React integration exists in astro.config.mjs:

   import { defineConfig } from 'astro/config'
   import react from '@astrojs/react'
   
   export default defineConfig({
     integrations: [react()],
   })
   

   Create a .env file at the project root:

   PUBLIC_COMETCHAT_APP_ID=your_app_id
   PUBLIC_COMETCHAT_REGION=your_region
   PUBLIC_COMETCHAT_AUTH_KEY=your_auth_key
   # For one-to-one and tab-based examples
   PUBLIC_COMETCHAT_LOGIN_UID=cometchat-uid-3
   PUBLIC_COMETCHAT_TARGET_UID=cometchat-uid-1
   
3. Initialize CometChat (UI Kit)

   Shared initializer that reads from environment variables:

   // src/lib/cometchat-init.js
   import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
   
   const APP_ID   = import.meta.env.PUBLIC_COMETCHAT_APP_ID;
   const REGION   = import.meta.env.PUBLIC_COMETCHAT_REGION;
   const AUTH_KEY = import.meta.env.PUBLIC_COMETCHAT_AUTH_KEY;
   
   export async function initCometChat() {
     if (!APP_ID || !REGION || !AUTH_KEY) {
       throw new Error("Missing PUBLIC_COMETCHAT_* env vars.");
     }
   
     const settings = new UIKitSettingsBuilder()
       .setAppId(APP_ID)
       .setRegion(REGION)
       .setAuthKey(AUTH_KEY) // use Auth Tokens in prod
       .subscribePresenceForAllUsers()
       .build();
   
     await CometChatUIKit.init(settings);
   }
   
   export async function ensureLogin(uid) {
     const existing = await CometChatUIKit.getLoggedinUser();
     if (existing && existing.getUid() !== uid) {
       await CometChatUIKit.logout();
     }
     const current = await CometChatUIKit.getLoggedinUser();
     if (!current) {
       await CometChatUIKit.login(uid);
     }
   }
   

   Replace placeholders with actual CometChat credentials before testing.

4. User Login

   The example islands handle login automatically using ensureLogin(uid) from src/lib/cometchat-init.js. Configure PUBLIC_COMETCHAT_LOGIN_UID (and PUBLIC_COMETCHAT_TARGET_UID for one-to-one) in .env.

   Auth Key is for development/POC only. Use Auth Token in production.

   Test UIDs: cometchat-uid-1 through cometchat-uid-5.

5. Choose a Chat Experience

   Three layout options:

   Conversation List + Message View

   Two-panel layout: conversation list on the left, active chat on the right. Supports 1:1 and group conversations with real-time updates.

   

   Integrate Conversation List + Message

   One-to-One/Group Chat

   Single chat window without a conversation list. Supports both 1:1 and group messaging.

   

   Integrate One-to-One/Group Chat

   Tab-Based Chat Experience

   Tab navigation between Chat, Call Logs, Users, and Settings. Works across desktop and mobile.

   

   Integrate Tab-Based Chat

Build Your Own Chat Experience

For full control over the chat interface, use individual components directly:

• React Sample App
• Core Features
• Components
• Themes
• Build with SDK

Next Steps

Conversation List + Message

Two-panel layout with conversation list and message view.

One-to-One Chat

Focused direct messaging experience without a sidebar.

Tab-Based Chat

Multi-tab navigation for chats, calls, users, and settings.

Advanced Customizations

Customize colors, fonts, and styles.