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

# Directory Structure

> How the exported UI Kit Builder code is organized for Next.js, and which parts are yours to edit.

The exported app has **two halves**, and the difference decides where you make changes:

| Folder | Who owns it | On re-export |
| - | - | - |
| `src/CometChat/` | CometChat. The sample app, shipped as-is. | **Copy the new one over yours** — edits here are lost |
| `src/builder/`, and the files you add under `src/app/` | You. Settings, theming, localization and the app shell. | Regenerated in the download too — keep your own, and take across only `cometchat-builder-settings.json` if you changed settings in the Builder |

Both folders are required: `src/CometChat` reads its configuration from `src/builder`.

> [!NOTE]
>
> This split is new in [React UI Kit v7](https://www.cometchat.com/docs/ui-kit/react/overview.md). If you are upgrading from
> [v6](https://www.cometchat.com/docs/ui-kit/react/v6/overview.md), `CometChatApp.tsx`,
> `CometChatSettings.ts`, `CometChat/context/CometChatContext.tsx` and
> `CometChat/utils/utils.ts` no longer exist — see
> [Integration](https://www.cometchat.com/docs/chat-builder/nextjs/integration.md) for the replacements.

***

## Project Structure Overview

The exported package is a Vite app. In a Next.js project you copy its two folders into `src/` and add
your own entry files under `src/app/` — [Integration](https://www.cometchat.com/docs/chat-builder/nextjs/integration.md) has the full
steps.

```
your-next-app/
│── src/
│   ├── app/
│   │   ├── CometChatNoSSR/
│   │   │   ├── CometChatNoSSR.tsx      ← initialization, SettingsProvider
│   │   │   └── CometChatAppShell.tsx   ← the app shell, yours to edit
│   │   ├── CometChatAppWrapper.tsx     ← loads the chat with ssr: false
│   │   └── page.tsx
│   ├── CometChat/
│   │   ├── assets/
│   │   ├── components/
│   │   ├── config/
│   │   ├── context/
│   │   ├── hooks/
│   │   ├── locales/
│   │   ├── styles/
│   │   ├── utils/
│   │   └── decl.d.ts
│   ├── builder/
│   │   ├── cometchat-builder-settings.json
│   │   ├── builderSettings.ts
│   │   ├── useBuilderTheme.ts
│   │   ├── colorUtils.ts
│   │   ├── customHooks.ts
│   │   ├── localization.ts
│   │   ├── styleConfig.ts
│   │   └── shell.css
│── eslint.config.mjs
│── next.config.ts
│── package.json
│── tsconfig.json
```

***

## 1. `src/CometChat/` — the CometChat sample app

The chat experience itself, built on the CometChat UI Kit. Treat this folder as vendored: read it, but make your changes through `src/builder/` and your builder settings instead.

### 1.1 `assets/`

Icons and images used by the sample app's components.

### 1.2 `components/`

Each subfolder is one screen or feature, with its `.tsx` and `.css` files:

| Component | Purpose |
| - | - |
| `CometChatAddMembers/` | Adds members to a group |
| `CometChatAIAssistant/` | The AI assistant chat experience |
| `CometChatCallLog/` | Call history, details, participants and recordings |
| `CometChatCreateGroup/` | Creating new groups |
| `CometChatCredentials/` | Credentials screen from the standalone sample app — unused here, since credentials live in `CometChatNoSSR.tsx` |
| `CometChatDetails/` | User and group details panels, including banned members |
| `CometChatHome/` | The main home screen, and the layout that places every other panel |
| `CometChatJoinGroup/` | Joining group chats, including password-protected ones |
| `CometChatLogin/` | Login screen with sample users |
| `CometChatMessages/` | Core chat interface for one-on-one and group chats |
| `CometChatNewChat/` | Starting a new conversation |
| `CometChatSelector/` | The sidebar: chats, calls, users and groups |
| `CometChatThreadPanel/` | Threaded conversations |
| `CometChatTransferOwnership/` | Transferring group ownership |

### 1.3 `config/` — settings plumbing

Connects your builder settings to the components:

* **`settings.types.ts`** — the `CometChatSettingsInterface` type and its sub-types.
* **`defaultSettings.ts`** — the fallbacks, plus `resolveSettings()`, which merges yours over
  them. This is why a partial settings file is safe. It exports two sets, and the difference
  matters: `storedSettingsDefaults` fills the gaps whenever a settings file is present, which is
  always in an exported app, and is what the Default column on
  [UI Kit Builder Settings](https://www.cometchat.com/docs/chat-builder/nextjs/builder-settings.md) documents. `defaultSettings` turns every feature on and applies
  only with no `SettingsProvider` at all — the sample app run bare.
* **`SettingsContext.tsx`** — `SettingsProvider` and the `useSettings()` hook.
* **`useFeatureProps.ts`** — turns settings into the UI Kit component props that switch features on and off.

### 1.4 `context/`

* **`AppContext.tsx`** — app-wide state such as the selected conversation, user or group.
* **`appReducer.ts`** — the reducer behind `AppContext`.

### 1.5 `hooks/`

* **`useIsMobile.ts`** — switches to the single-pane layout when the chat area is narrow. It measures the app's own container, so it works when the chat is embedded in a smaller part of your page, not only when the browser window is small.

### 1.6 `locales/`

Translation files for the sample app's own text, one JSON file per language, collected by `index.ts`.

### 1.7 `styles/`

* **`App.css`** — layout styles for the whole app. Imported once, from your app shell.

### 1.8 `utils/`

* **`assetUrl.ts`** — returns the URL of an imported image whichever bundler built it. Next.js imports images as objects rather than URLs, and this smooths that over.

### 1.9 `decl.d.ts`

TypeScript declarations that let components import `.svg` and `.png` files.

***

## 2. `src/builder/` — your configuration

Owned by you. This is where the choices you made in the UI Kit Builder live.

| File | What it does |
| - | - |
| `cometchat-builder-settings.json` | Your builder settings, written by the dashboard at export and safe to edit by hand. See [UI Kit Builder Settings](https://www.cometchat.com/docs/chat-builder/nextjs/builder-settings.md) |
| `builderSettings.ts` | Loads that JSON and exports `builderSettings` for `SettingsProvider` |
| `useBuilderTheme.ts` | Applies your theme, brand color and typography to the app |
| `colorUtils.ts` | Derives the lighter and darker brand shades used across the UI |
| `customHooks.ts` | `useSystemColorScheme`, which follows the OS light or dark mode when your theme is `system` |
| `localization.ts` | `setupLocalization()`, which registers the sample app's translations with the UI Kit |
| `styleConfig.ts` | The font-size scales `useBuilderTheme` applies, and the option lists the Builder shows for fonts and sizes |
| `shell.css` | Page-level styles for the standalone app: the page reset, the chat's full-height container, and the "credentials missing" screen |

***

## 3. The files you add under `src/app/`

* **`CometChatNoSSR/CometChatNoSSR.tsx`** — holds your app credentials (`COMETCHAT_CONSTANTS`), initializes the UI Kit once, and renders the shell inside `SettingsProvider`.
* **`CometChatNoSSR/CometChatAppShell.tsx`** — the app shell. Applies the theme, handles login and logout, and renders `CometChatHome` or `CometChatLogin`. This replaces v6's `CometChatApp` component and is yours to edit.
* **`CometChatAppWrapper.tsx`** — a Client Component that loads the chat with `ssr: false`, so the rest of your app keeps server rendering.

> [!NOTE]
>
> The exported package's own `src/index.tsx` and `src/App.tsx` are for running it
> standalone with Vite. In Next.js their job is done by the three files above.

***

## 4. Project files worth knowing

| File | Purpose |
| - | - |
| `tsconfig.json` | Must include `"resolveJsonModule": true` — `builderSettings` imports the settings JSON directly |
| `eslint.config.mjs` | Exclude `src/CometChat/**` and `src/builder/**`; Next.js's rules are stricter than the ones that folder is written against |
| `next.config.ts` | No changes needed. Both Turbopack and webpack work |

The exported package also ships `README.md`, `NEXT_JS.md`, `CHANGELOG.md` and a `project-info/` folder with the settings reference and this structure document.

***

## Where to make a change

| You want to… | Edit |
| - | - |
| Turn a feature on or off | `src/builder/cometchat-builder-settings.json` |
| Change theme, brand color or font | `src/builder/cometchat-builder-settings.json` (`style.*`) |
| Change what the app renders around the chat | `src/app/CometChatNoSSR/CometChatAppShell.tsx` |
| Change credentials | `src/app/CometChatNoSSR/CometChatNoSSR.tsx` |
| Add a language | `src/builder/localization.ts` |
| Restyle a UI Kit component | Your own CSS, using the UI Kit's CSS variables — see [Advanced Theming](https://www.cometchat.com/docs/ui-kit/react/theming.md) |

> [!WARNING]
>
> Avoid editing anything inside `src/CometChat/`. That folder is replaced on
> every upgrade, so changes there are lost — and it is the one part of the app
> that is not yours.

> **[UI Kit Builder Settings](https://www.cometchat.com/docs/chat-builder/nextjs/builder-settings.md)**
>
> Every setting in the JSON file, with its default.

> **[Customizations](https://www.cometchat.com/docs/chat-builder/nextjs/builder-customisations.md)**
>
> Go further than the settings file.


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