UI Kit Builder Integration

Step-by-step guide to integrating CometChat UI Kit Builder into your Next.js app, with SSR handled.

The UI Kit Builder simplifies integrating CometChat’s UI Kit into your Next.js application — quickly set up chat, customize UI elements, and add features without extensive coding.

The UI Kit Builder exports a React code package. There is no separate Next.js export — this guide covers dropping that package into a Next.js App Router project, which mainly means keeping it out of server rendering.

Complete Integration Workflow

1. Design Your Chat Experience - Use the UI Kit Builder to customize layouts, features, and styling.
2. Review and Export - Review which features will be enabled in your Dashboard, toggle them on/off, and download the generated code package.
3. Preview Customizations - Optionally, preview the chat experience before integrating it into your project.
4. Integration - Integrate into your existing application.
5. Customize Further - Explore advanced customization options to tailor the chat experience.

---

Requirements

Next.js	15 or 16, App Router
React	19
UI Kit	@cometchat/chat-uikit-react v7 — see the React UI Kit v7 docs
TypeScript	resolveJsonModule: true — new Next.js projects already have it

Both Turbopack and webpack work, and no next.config changes are needed.

---

Launch the UI Kit Builder

1. Log in to your CometChat Dashboard.
2. Select your application from the list.
3. Navigate to Chat & Messaging → Get Started.
4. Choose your platform and click Launch UI Kit Builder.

---

Review Your Export

When you click Export, a “Review Your Export” modal appears (Step 1 of 3). This lets you:

• Review features — See which features will be enabled in your CometChat Dashboard based on your UI Kit configuration
• Toggle features — Turn individual features on/off before export
• AI User Copilot — Requires an OpenAI API key (you’ll configure this in the next step)

Only checked features will be enabled in your Dashboard. You can always modify these settings later in the CometChat Dashboard.

---

Integrate into Your Project

Step 1: Install Dependencies

npm install @cometchat/chat-uikit-react@^7.2.4 @cometchat/chat-sdk-javascript@^4.2.0 @cometchat/calls-sdk-javascript@^5.0.6

Step 2: Copy Two Folders

Copy both of these into your project’s src directory, next to src/app:

Folder	What it is
src/CometChat	The CometChat sample app. Treat it as vendored — it is replaced wholesale on every UI Kit release, so edits here are lost.
src/builder	Your builder settings, theming and localization. This is the part you own and customize.

src/
│── app/
│── builder/
│── CometChat/

Both are required, and they must stay side by side: src/CometChat reads its configuration from src/builder.

Copying only src/CometChat leaves the app without its settings, theme and localization. The split is deliberate: because your customizations sit outside the vendored folder, a later re-export means copying src/CometChat alone.

Step 3: Exclude the Copied Folders from ESLint

Next.js’s lint rules are stricter than the ones the CometChat folder is written against, and npm run lint reports errors in it on Next.js 16. Since you don’t edit that folder, exclude both copied folders in eslint.config.mjs:

"src/CometChat/**",
"src/builder/**",

Step 4: Initialize CometChat UI Kit

Create src/app/CometChatNoSSR/CometChatNoSSR.tsx. Initialization also wires up SettingsProvider, which feeds your builder settings into the app.

src/app/
│── CometChatNoSSR/
│   ├── CometChatNoSSR.tsx
│   ├── CometChatAppShell.tsx
│── CometChatAppWrapper.tsx
│── page.tsx

"use client";

import { useEffect, useState } from "react";
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";
import CometChatAppShell from "./CometChatAppShell";
import { SettingsProvider } from "../../CometChat/config/SettingsContext";
import { builderSettings } from "../../builder/builderSettings";
import { setupLocalization } from "../../builder/localization";

export const COMETCHAT_CONSTANTS = {
  APP_ID: "", // Replace with your App ID
  REGION: "", // Replace with your App Region
  AUTH_KEY: "", // Replace with your Auth Key
};

// Cached so init runs once, even though React Strict Mode runs effects twice in development.
let initPromise: Promise<void> | undefined;

function initCometChat(): Promise<void> {
  if (!initPromise) {
    const uiKitSettings = new UIKitSettingsBuilder()
      .setAppId(COMETCHAT_CONSTANTS.APP_ID)
      .setRegion(COMETCHAT_CONSTANTS.REGION)
      .setAuthKey(COMETCHAT_CONSTANTS.AUTH_KEY)
      .subscribePresenceForAllUsers()
      // Without this the call buttons do not render at all.
      .setCallingEnabled(true)
      .build();

    initPromise = Promise.resolve(CometChatUIKit.init(uiKitSettings)).then(() => {
      setupLocalization();
    });
  }
  return initPromise;
}

export default function CometChatNoSSR() {
  const [ready, setReady] = useState(false);

  useEffect(() => {
    initCometChat()
      .then(() => setReady(true))
      .catch((error) => console.error("CometChat UI Kit failed to initialise", error));
  }, []);

  if (!ready) return null;

  return (
    <SettingsProvider settings={builderSettings}>
      <CometChatAppShell />
    </SettingsProvider>
  );
}

Your app credentials (APP_ID, AUTH_KEY, REGION) are prepopulated in the exported code. If you need different credentials, find them in the Credentials block of your app’s Overview section on the CometChat Dashboard.

Upgrading from v6? CometChatProvider no longer comes from a local CometChat/context/CometChatContext, setupLocalization has moved to builder/localization, and CometChat/utils/utils and CometChat/CometChatApp no longer exist. The code above is the v7 replacement for all four.

Session storage. To use session storage instead of the default local storage, configure it during initialization — see the Setting Session Storage Mode guide.

Step 5: User Authentication

CometChat uses a UID (User ID) to identify each user. You can create users on the CometChat Dashboard, with a CometChat SDK method, or via the API — or use the pre-generated test users cometchat-uid-1 through cometchat-uid-5.

The app shell in Step 6 already handles this: it renders CometChatLogin until someone is logged in, and listens for SDK login and logout events afterwards.

To log a user in programmatically instead, do it inside the cached init promise, so it also runs only once:

initPromise = Promise.resolve(CometChatUIKit.init(uiKitSettings)).then(async () => {
  setupLocalization();
  if (!CometChatUIKit.getLoggedInUser()) {
    await CometChatUIKit.login("cometchat-uid-1"); // Replace with your user's UID
  }
});

Auth Key vs Auth Token

Auth Key is perfect for prototyping. For production apps, switch to Auth Token (CometChatUIKit.loginWithAuthToken) for secure authentication. See Authentication and User Management for details.

Step 6: Render the App Shell

v7 has no CometChatApp component. Create src/app/CometChatNoSSR/CometChatAppShell.tsx — it is the integration point, and it is yours to edit:

import "../../CometChat/styles/App.css";
import "../../builder/shell.css";
import { useEffect, useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatProvider, CometChatUIKit } from "@cometchat/chat-uikit-react";
import { CometChatHome } from "../../CometChat/components/CometChatHome/CometChatHome";
import CometChatLogin from "../../CometChat/components/CometChatLogin/CometChatLogin";
import { AppContextProvider } from "../../CometChat/context/AppContext";
import { useSettings } from "../../CometChat/config/SettingsContext";
import useSystemColorScheme from "../../builder/customHooks";
import { useBuilderTheme } from "../../builder/useBuilderTheme";

export default function CometChatAppShell() {
  // UI Kit init has already finished before this renders, so the session can be read up front.
  const [loggedInUser, setLoggedInUser] = useState<CometChat.User | null>(
    () => CometChatUIKit.getLoggedInUser() ?? null
  );
  const { style } = useSettings();
  const systemTheme = useSystemColorScheme();

  // The UI Kit accepts only 'light' | 'dark' — resolving 'system' is the consumer's job.
  const theme: "light" | "dark" =
    style.theme === "light" || style.theme === "dark" ? style.theme : systemTheme;

  useBuilderTheme(style, theme);

  useEffect(() => {
    CometChat.addLoginListener(
      "app-login-listener",
      new CometChat.LoginListener({
        loginSuccess: (user: CometChat.User) => setLoggedInUser(user),
        logoutSuccess: () => setLoggedInUser(null),
      })
    );

    return () => CometChat.removeLoginListener("app-login-listener");
  }, []);

  const handleLogout = async () => {
    await CometChatUIKit.logout();
    setLoggedInUser(null);
  };

  return (
    /* The chat UI fills its parent, so give it explicit dimensions. */
    <div className="App" style={{ width: "100vw", height: "100dvh" }}>
      <CometChatProvider theme={theme} locale="en-us">
        <AppContextProvider>
          {loggedInUser ? (
            <CometChatHome loggedInUser={loggedInUser} onLogout={handleLogout} />
          ) : (
            <CometChatLogin onLoginSuccess={setLoggedInUser} />
          )}
        </AppContextProvider>
      </CometChatProvider>
    </div>
  );
}

Sizing. .App sets the size — change its style to fit the chat into part of your page. That is not enough on its own: the .cometchat element that CometChatProvider renders must fill it too, or the message list grows with its content and pushes the composer off-screen. builder/shell.css does this with:

.App > .cometchat {
  height: 100%;
}

shell.css also resets the body margin and font — copy the rule into your own stylesheet instead if you’d rather keep your page’s body styles.

Step 7: Disable SSR and Render the Component

Load CometChatNoSSR.tsx with server-side rendering disabled, while keeping SSR for the rest of your app. ssr: false is only allowed in a Client Component, so create src/app/CometChatAppWrapper.tsx:

"use client";

import dynamic from "next/dynamic";

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

export default function CometChatAppWrapper() {
  return <CometChatNoSSR />;
}

Now import and use the wrapper in your page:

import CometChatAppWrapper from "./CometChatAppWrapper";

export default function Home() {
  return (
    <>
      {/* Other components or content */}
      <CometChatAppWrapper />
    </>
  );
}

Why disable SSR?

• The CometChat UI Kit and the CometChat folder use browser APIs (window, document, WebSockets) as soon as they load.
• Next.js pre-renders pages on the server, where those APIs don’t exist — the build fails with window is not defined.
• { ssr: false } loads CometChatNoSSR.tsx only in the browser.

Step 8: Customize Through Settings

Layout and feature choices live in src/builder/cometchat-builder-settings.json, which the dashboard writes at export time and which you can edit by hand afterwards. Anything the file omits falls back to a default, so partial files are safe.

Setting	Effect
layout.withSideBar	false renders a single chat pane with no conversations list.
layout.chatType	user or group — which chat opens when there is no sidebar.
style.theme	light, dark, or system.
style.color, style.typography	Brand color, text colors and font, applied by useBuilderTheme.
chatFeatures.*, callFeatures.*	Per-feature toggles, mapped to UI Kit props by buildFeatureProps.

Group action messages (joins, leaves, kicks, bans) are the exception: there is no settings key for them. They are on by default, and the only way to change that from code is the showGroupActionMessages prop on CometChatHome — the same prop v6 had on CometChatApp. Whether they are generated at all is an app-level choice: Chat > Settings > Include Group Actions in the dashboard.

Every setting is described in UI Kit Builder Settings.

Step 9: Run the App

npm run dev

---

Troubleshooting

window is not defined during build or dev. Something is importing the chat outside the ssr: false boundary. Every import of CometChat/ or builder/ must be reached through CometChatNoSSR.

TypeScript cannot import the settings JSON. Add "resolveJsonModule": true to tsconfig.json and restart the dev server. builderSettings imports the JSON directly.

npm run lint reports errors inside src/CometChat. Add the two ignore entries from Step 3.

The chat renders but has no height. builder/shell.css is not imported, or your own CSS overrides it. See the sizing note in Step 6.

No call buttons in the message header. setCallingEnabled(true) is missing from Step 4. Calling is off by default, and the header hides both buttons entirely rather than rendering them inert.

Call buttons render but calls fail. @cometchat/calls-sdk-javascript is not installed.

---

Next Steps

Customizations

Adjust component props, behavior, and UI elements.

UI Kit Builder Settings

Understand the settings file and feature toggles.

Directory Structure

See how the exported code is organized.

Advanced Theming

Customize colors, typography, and styling to match your brand.

---