Next.js Integration

Add CometChat to a Next.js (App Router) app in 4 steps: create project, install, wrap in CometChatProvider, 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
Setup	Wrap app in <CometChatProvider appId="..." region="..." authKey="..." uid="...">
Auth Key	Dev/testing only. Use authToken prop in production
CSS	import "@cometchat/chat-uikit-react/styles";
SSR	CometChat components must be loaded with dynamic(() => import(...), { ssr: false })
Calling	Optional. Install @cometchat/calls-sdk-javascript and set callingEnabled prop
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 wraps your chat UI in 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 { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
  CometChatProvider,
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
} from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/styles";

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

  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
      appId="YOUR_APP_ID"
      region="YOUR_REGION"
      authKey="YOUR_AUTH_KEY"
      uid="cometchat-uid-1"
    >
      <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. CometChatProvider handles init, login, and all context setup automatically. For advanced use cases (custom login flows, individual providers), see the CometChatProvider guide.

For production, use the authToken prop instead of authKey + 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.

---

iFrame Embedding

If your Next.js app runs inside an <iframe>, additional configuration is needed to ensure dialogs and portals mount in the correct frame. Documentation will be available once iframe support is finalized.

---

Next Steps

Components Overview

Browse all prebuilt UI components

Theming

Customize colors, fonts, and styles

Plugins

Customize message rendering

Troubleshooting

Common issues and fixes