Next.js Integration

Add CometChat to a Next.js (App Router) app in 5 steps: create project, install, init + login, render, run.

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 loginWithAuthToken in production
SSR	CometChat components must be loaded with dynamic(() => import(...), { ssr: false })
Calling	Optional. Install @cometchat/calls-sdk-javascript and call .setCallingEnabled(true) on UIKitSettingsBuilder
Other frameworks	React.js · React Router · Astro

This guide walks you through adding CometChat to a Next.js (App Router) app. 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 a Next.js Project

npx create-next-app@latest my-app --typescript
cd my-app

When prompted, select App Router (the default in Next.js 14+).

---

Step 2 — Install the UI Kit

npm

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

yarn

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 CometChat Client Component

CometChat uses browser APIs and cannot run in Server Components. Create a 'use client' component that initializes the SDK, logs in, and renders your chat UI 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

app/CometChatClient.tsx

'use client';

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 CometChatClient() {
  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>
  );
}

'use client' is required because CometChat components use browser APIs. Init and login happen in a useEffect, and the provider only mounts after login succeeds. See the CometChatProvider guide for all provider 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 — Import with SSR Disabled

In your page file, use dynamic() with ssr: false to prevent the CometChat component from rendering on the server.

app/page.tsx

import dynamic from 'next/dynamic';

const CometChatClient = dynamic(() => import('./CometChatClient'), { ssr: false });

export default function Home() {
  return <CometChatClient />;
}

You must use dynamic(() => import(...), { ssr: false }). Without this, Next.js will attempt to render CometChat on the server, causing errors like window is not defined or document is not defined.

---

Step 5 — Run

npm run dev

Open http://localhost:3000. 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