> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

![](https://mintcdn.com/cometchat-22654f5b/dJPACx1AKXUTpAHt/images/uikit-builder-preview.png?fit=max\&auto=format\&n=dJPACx1AKXUTpAHt\&q=85\&s=8a801797bb6c3c9af164502d41708a4a)

> [!NOTE]
>
> 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](https://www.cometchat.com/docs/ui-kit/react/overview.md) 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**](https://app.cometchat.com).
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)

![](https://mintcdn.com/cometchat-22654f5b/dJPACx1AKXUTpAHt/images/ui-kit-builder-review-export.png?fit=max\&auto=format\&n=dJPACx1AKXUTpAHt\&q=85\&s=be0621d28ffccdd47bc536a399fe16a0)

> [!NOTE]
>
> Only checked features will be enabled in your Dashboard. You can always modify
> these settings later in the [CometChat Dashboard](https://app.cometchat.com).

***

## **Integrate into Your Project**

### **Step 1: Install Dependencies**

```bash theme={null}
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`.

> [!WARNING]
>
> 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`:

```js theme={null}
"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
```

```tsx theme={null}
"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>
  );
}
```

> [!NOTE]
>
> 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](https://app.cometchat.com) on the CometChat Dashboard.

> [!NOTE]
>
> **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](https://www.cometchat.com/docs/ui-kit/react/methods.md#setting-session-storage-mode).

### **Step 5: User Authentication**

CometChat uses a UID (User ID) to identify each user. You can create users on the [CometChat Dashboard](https://app.cometchat.com), with a [CometChat SDK method](https://www.cometchat.com/docs/ui-kit/react/methods.md), or [via the API](https://www.cometchat.com/docs/rest-api/users/create.md) — 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:

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

> [!NOTE]
>
> **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](https://www.cometchat.com/docs/fundamentals/user-auth.md) 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:

```tsx theme={null}
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:

```css theme={null}
.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`:

```tsx theme={null}
"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:

```tsx theme={null}
import CometChatAppWrapper from "./CometChatAppWrapper";

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

> [!WARNING]
>
> **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](https://www.cometchat.com/docs/chat-builder/nextjs/builder-settings.md).

### **Step 9: Run the App**

```bash theme={null}
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](https://www.cometchat.com/docs/chat-builder/nextjs/builder-customisations.md)**
>
> Adjust component props, behavior, and UI elements.

> **[UI Kit Builder Settings](https://www.cometchat.com/docs/chat-builder/nextjs/builder-settings.md)**
>
> Understand the settings file and feature toggles.

> **[Directory Structure](https://www.cometchat.com/docs/chat-builder/nextjs/builder-dir-structure.md)**
>
> See how the exported code is organized.

> **[Advanced Theming](https://www.cometchat.com/docs/ui-kit/react/theming.md)**
>
> Customize colors, typography, and styling to match your brand.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.