cometchat-angular-core— agent skill

Purpose

Foundational skill for every CometChat Angular UI Kit v5 (@cometchat/chat-uikit-angular@5) integration. It teaches HOW CometChat works in Angular v5 — initialization order, the UIKitSettingsBuilder pattern, login, environment config, standalone-component wiring, and the anti-patterns that break real apps.

Angular UI Kit v5 is standalone-component-based and requires Angular 17–21. This is a hard requirement — the package's peer range is @angular/core / @angular/common >=17.0.0 <22.0.0. Projects on older Angular must upgrade before using UI Kit v5.

Read this skill first, before any placement, components, or patterns skill.

Ground truth: @cometchat/[email protected] kit source (projects/cometchat-uikit/src/lib) + docs/ui-kit/angular. Official docs: https://www.cometchat.com/docs/ui-kit/angular/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify any non-obvious symbol against the installed package types before relying on it.

2. Install

npm install @cometchat/chat-uikit-angular@^5
# Calls features only — also install the calls SDK peer:
npm install @cometchat/calls-sdk-javascript@^5

⚠️ Angular 22 is NOT supported — pin the CLI to 21 when scaffolding (verified — real `npm install` ERESOLVE). The kit's peer range is @angular/core/@angular/common >=17.0.0 <22.0.0. npx @angular/cli@latest new … now installs Angular 22, so npm install @cometchat/chat-uikit-angular@^5 then hard-fails with ERESOLVE … peer @angular/common@">=17.0.0 <22.0.0". For a fresh project scaffold with a supported major: npx -y @angular/cli@21 new <app> … (Angular 17–21 all work). Existing projects on 22 must stay on the prior major until the kit widens its range.

⚠️ `ng build` (production) fails the default bundle budget — raise it. The kit's initial bundle is ~3.78 MB; Angular's default production budgets cap initial at 1 MB maximumError, so the literal ng build exits non-zero with bundle initial exceeded maximum budget. In angular.json raise (or remove) the initial budget — e.g. set maximumError to 5mb — or build with --configuration development while iterating. This is a guaranteed failure otherwise; it is not a problem with your code.

The chat SDK (@cometchat/chat-sdk-javascript@^4.1.8), dompurify@^3, and (for calls only) the calls SDK are peer deps. @cometchat/calls-sdk-javascript is an optional peer — npm won't auto-install it; add it yourself when you need calling. There is no @cometchat/uikit-shared / -elements / -resources in v5 — do not install or import them.

Stylesheet (mandatory — layout + tokens break without it)

Add the kit's CSS-variable stylesheet via angular.json → ...build.options.styles (use this form — it's the one that builds):

"styles": [
  "src/styles.css",
  "node_modules/@cometchat/chat-uikit-angular/styles/css-variables.css"
]

⚠️ Do NOT use the `@import` package-specifier form on Angular 17+ (the default @angular/build esbuild builder). @import '@cometchat/chat-uikit-angular/styles/css-variables.css'; fails the build — Could not resolve … the path "./styles/css-variables.css" is not exported by package — because the package exports map only exposes . and ./package.json. The angular.json styles array above works because the full node_modules/... path bypasses the exports map. (Verified — real ng build.)

Assets (mandatory — icons break without it)

angular.json → projects.<app>.architect.build.options.assets:

{
  "glob": "**/*",
  "input": "node_modules/@cometchat/chat-uikit-angular/src/lib/assets",
  "output": "assets"
}

The kit ships its SVG icons under src/lib/assets in the published package — map that to output: assets. Missing this = broken icons throughout the kit. It's the most commonly missed step.

3. The init → login → render order

CometChat Angular has exactly one valid lifecycle:

CometChatUIKit.init(UIKitSettings)  →  CometChatUIKit.login(uid)  →  render <cometchat-*> components

Both init() and login() return Promises. Breaking this order produces a blank component, a "CometChat is not initialized" console error, or a hung login.

File-based init with cometchat-settings.json (recommended where available)

Version requirement (ENG-35866 — Skills Telemetry). CometChatUIKit.initFromSettings(settings) reads a cometchat-settings.json object and lets the SDK self-report integrationSource = "ai-agent". It ships GA in `@cometchat/chat-uikit-angular >= 5.0.3` + `@cometchat/chat-sdk-javascript >= 4.1.11` (npm latest). On an older kit (<= 5.0.2) the method does not exist — only the UIKitSettingsBuilder + init() path below works (reporting integrationSource = "manual"); use that fallback. (The kit routes initFromSettings to the SDK's CometChat.initFromSettings, which stamps ai-agent — plain init(settings) does not; ENG-36203.)

Step 1 — create `cometchat-settings.json` at the project root (e.g. alongside angular.json). Fill appId / region / credentials.authKey from the CLI provision setup output; leave the rest at the defaults:

{
  "appId": "APP_ID_HERE",
  "region": "us",
  "credentials": {
    "authKey": "AUTH_KEY_HERE"
  },
  "chatSDK": {
    "presenceSubscription": {
      "type": "ALL_USERS",
      "roles": []
    },
    "autoEstablishSocketConnection": true,
    "adminHost": null,
    "clientHost": null
  },
  "callsSDK": {
    "host": null,
    "adminHost": null,
    "clientHost": null,
    "callsHost": null
  },
  "uiKit": {
    "subscribePresenceForAllUsers": true
  }
}

Step 2 — init in `main.ts` by importing the JSON. Angular CLI projects have resolveJsonModule: true by default, so the import is type-safe:

// main.ts — initFromSettings ships GA in @cometchat/chat-uikit-angular >= 5.0.3 (ENG-35866)
import { bootstrapApplication } from "@angular/platform-browser";
import { CometChatUIKit } from "@cometchat/chat-uikit-angular";
import { AppComponent } from "./app/app.component";
import { appConfig } from "./app/app.config";
import cometchatSettings from "../cometchat-settings.json";

CometChatUIKit.initFromSettings(cometchatSettings)
  .then(() => bootstrapApplication(AppComponent, appConfig))
  .catch((err) => console.error("CometChat init failed:", err));

• Do NOT gitignore `cometchat-settings.json`. The dev-mode authKey ships in the built bundle either way; production uses server-minted auth tokens.

UIKitSettingsBuilder — the init pattern (fallback — published kit; reports manual)

UIKitSettingsBuilder and UIKitSettings are exported from `@cometchat/chat-uikit-angular` (not uikit-shared, which no longer exists):

import { UIKitSettingsBuilder, CometChatUIKit } from "@cometchat/chat-uikit-angular";
import { environment } from "../environments/environment";

const settings = new UIKitSettingsBuilder()
  .setAppId(environment.cometchat.appId)
  .setRegion(environment.cometchat.region)          // "us" | "eu" | "in"
  .setAuthKey(environment.cometchat.authKey)        // dev only — omit in production
  .subscribePresenceForAllUsers()
  .build();

const initPromise = CometChatUIKit.init(settings);   // Promise<InitResult> | undefined

init() returns Promise<InitResult> | undefined (it returns undefined if settings are missing/invalid). Guard for the undefined case rather than blindly .then()-ing the result.

Builder methods (verified against v5 UIKitSettings.ts): setAppId, setRegion, setAuthKey, subscribePresenceForAllUsers, subscribePresenceForFriends, subscribePresenceForRoles(roles), setRoles(roles), setAutoEstablishSocketConnection(bool), setAdminHost, setClientHost, setStorageMode, setCallingEnabled(bool), setCallAppSettings, build().

Init must run once, before any chat component renders

The canonical pattern (used by both the docs and the kit's own sample app) is to init in `main.ts` and only bootstrap the Angular app once init resolves. Do NOT init inside a lazily-loaded route that mounts after a <cometchat-*> component could already be on screen.

// main.ts (Angular 17+ standalone bootstrap)
import { bootstrapApplication } from "@angular/platform-browser";
import { UIKitSettingsBuilder, CometChatUIKit } from "@cometchat/chat-uikit-angular";
import { AppComponent } from "./app/app.component";
import { appConfig } from "./app/app.config";
import { environment } from "./environments/environment";

// Fail loud if environment.cometchat values are EMPTY (env block missing, or
// the wrong environment file picked at build). Note: this catches empty/unset
// only — a non-empty placeholder like "YOUR_APP_ID" is truthy and passes, so
// still paste real values. Otherwise empty creds surface later as a cryptic
// init failure. (audit P0-5)
const cc = environment.cometchat;
if (!cc?.appId || !cc?.region || !cc?.authKey) {
  throw new Error(
    "CometChat credentials are empty in environment.cometchat — fill appId/region/authKey " +
      "in src/environments/environment.ts (and environment.prod.ts).",
  );
}

const settings = new UIKitSettingsBuilder()
  .setAppId(cc.appId)
  .setRegion(cc.region)
  .setAuthKey(cc.authKey)
  .subscribePresenceForAllUsers()
  .build();

// `init(...)` is typed `Promise<InitResult> | undefined` in v5.0.2, so coalesce to a
// Promise before chaining — `init(settings)?.then(...).catch(...)` still leaves the
// `.catch` on a possibly-undefined value and fails `tsc` strict (TS2532) on Angular 21.
(CometChatUIKit.init(settings) ?? Promise.resolve())
  .then(() => {
    bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err));
  })
  .catch((err) => console.error("CometChat init failed:", err));

Bootstrapping only after init resolves means every component that mounts afterward can safely assume CometChat is initialized. Login (dev user or token) then happens in the root component / a route guard / an auth service — see §4.

Filename convention — modern CLI scaffolds differ from these examples. Examples here use the classic AppComponent in src/app/app.component.ts. Angular CLI 17+ (and 21) scaffolds the root component as `App` in src/app/app.ts (no .component suffix), with app.config.ts + app.routes.ts. On a freshly-scaffolded project, import App (not AppComponent) from ./app/app and adapt the filenames — the wiring is identical, only the names changed.

Alternative — `APP_INITIALIZER`: if you prefer to bootstrap unconditionally and block on a DI provider, register an APP_INITIALIZER factory that returns the CometChatUIKit.init(settings) Promise. Angular blocks bootstrap until it resolves. Either way the rule holds: init must finish before any <cometchat-*> renders.

4. Login

Development mode — login(uid) takes a BARE STRING

import { CometChatUIKit } from "@cometchat/chat-uikit-angular";

const user = await CometChatUIKit.getLoggedinUser();   // async getter → Promise<User | null>
if (!user) {
  await CometChatUIKit.login("cometchat-uid-1");        // ← bare string, NOT { uid: "..." }
}

login() takes a string uid, not an object — its signature is login(uid: string): Promise<CometChat.User>. Passing { uid: "..." } fails type-checking. (Token login is a separate method — see Production.)

Every new CometChat app ships 5 pre-seeded test users — cometchat-uid-1 … cometchat-uid-5.

Reading the current user — three options

// 1. Sync getter — use in components, route guards, anywhere after login completes:
const user = CometChatUIKit.getLoggedInUser();      // User | null  (note capital "In")

// 2. Async getter — use inside the init/login flow:
const user = await CometChatUIKit.getLoggedinUser(); // Promise<User | null>  (note lowercase "in")

// 3. Reactive (idiomatic Angular) — react to login/logout in templates with the async pipe:
CometChatUIKit.loggedInUser$.subscribe(u => this.currentUser = u);

CometChatUIKitLoginListener exists only as an internal kit class — it is not exported from @cometchat/chat-uikit-angular's public API and has no public getLoggedInUser(). Use the static getters or the loggedInUser$ observable instead. Never hardcode a UID to identify the current user — in production it comes from your auth system.

Production mode

await CometChatUIKit.loginWithAuthToken(tokenFromYourBackend);

The backend mints the token via the CometChat REST API using the server-only REST API Key. See cometchat-angular-production.

Logout

await CometChatUIKit.logout();   // Promise<LogoutResult> — then navigate to your login route

5. Using components — standalone imports (no NgModule, no schema)

v5 components are standalone Angular components. Import the component class into the imports: [] of whatever standalone component renders it. They are real Angular components (not generic web components), so `CUSTOM_ELEMENTS_SCHEMA` is NOT needed — and there is no NgModule to register.

// chat.component.ts
import { Component } from "@angular/core";
import { CometChatConversationsComponent } from "@cometchat/chat-uikit-angular";

@Component({
  selector: "app-chat",
  standalone: true,
  imports: [CometChatConversationsComponent],   // import the class you use; no schema
  template: `<cometchat-conversations></cometchat-conversations>`,
})
export class ChatComponent {}

• Class names carry the `Component` suffix (CometChatConversationsComponent); the HTML selectors do not (<cometchat-conversations>).
• Import only the components you actually use.
• There is no composite <cometchat-conversations-with-messages> in v5 — build a two-pane layout by composing cometchat-conversations with cometchat-message-header / -list / -composer (see cometchat-angular-placement).

Using an NgModule-based app (not yet migrated to standalone)? You can still add these standalone classes to an @NgModule({ imports: [...] }) — standalone components are importable into NgModules. You still do not need CUSTOM_ELEMENTS_SCHEMA.

See cometchat-angular-components for the full catalog of selectors, @Input/@Output bindings, and slot templates.

6. Environment variables

Angular has no .env / process.env. Config lives in src/environments/environment.ts.

// src/environments/environment.ts (development)
export const environment = {
  production: false,
  cometchat: {
    appId: "YOUR_APP_ID",
    region: "us",                 // "us" | "eu" | "in"
    authKey: "YOUR_AUTH_KEY",     // dev only — never in production builds
  },
};

// src/environments/environment.prod.ts (production)
export const environment = {
  production: true,
  cometchat: {
    appId: "YOUR_APP_ID",
    region: "us",
    // No authKey in production — mint auth tokens server-side
    tokenEndpoint: "https://api.yourapp.com/cometchat-token",
  },
};

Never put the REST API Key in any environment file. Angular bundles environment.ts into client JS — the REST API Key is server-only.

7. Theming — CSS variables (no theme service)

v5 has no `CometChatThemeService` and no programmatic palette API. Theming is done with CSS custom properties (--cometchat-*), the same model as the React kit. Light/dark mode is a single setter:

CometChatUIKit.themeMode = "dark";   // 'light' | 'dark'

/* styles.css — override brand + tokens globally */
:root {
  --cometchat-primary-color: #6852D6;
}

See cometchat-angular-theming for the full CSS-variable token reference and dark-mode strategy. Do not reach for CometChatThemeService / theme.palette.setPrimary() — no such programmatic palette API exists; theming is CSS-variable only.

8. Anti-patterns

1. Don't target Angular ≤16. UI Kit v5's peer range is Angular 17–21 (>=17.0.0 <22.0.0). On older Angular, upgrade before integrating.
2. Don't install or import `@cometchat/uikit-shared` / `-elements` / `-resources`. They don't exist in the v5 dependency set — everything is in @cometchat/chat-uikit-angular.
3. Don't add `CUSTOM_ELEMENTS_SCHEMA` for CometChat components — they are real Angular components (not generic web components), so the schema is unnecessary.
4. Don't call `login({ uid })`. v5 takes a bare string: login("cometchat-uid-1").
5. Don't use `CometChatUIKitLoginListener` — it's an internal class, not public API. Use CometChatUIKit.getLoggedInUser() / getLoggedinUser() / loggedInUser$.
6. Don't use `CometChatThemeService` — it doesn't exist in v5. Theme via CSS variables + themeMode.
7. Don't reach for `<cometchat-conversations-with-messages>` — removed in v5. Compose the layout from the individual components.
8. Don't init inside a lazy-loaded route. Init must complete before any <cometchat-*> renders — use APP_INITIALIZER or gate on an isReady flag.
9. *Don't render `<cometchat-> before init+login resolve.** Gate with *ngIf`.
10. Don't bundle the REST API Key in any src/ file — Angular ships src/ to the client.

9. SDK access

For raw SDK calls (e.g. CometChat.getUser(uid)), import the CometChat namespace directly from the chat SDK peer dependency:

import { CometChat } from "@cometchat/chat-sdk-javascript";

Use the kit's CometChatUIKit.* helpers (sendTextMessage, createUser, updateUser, etc.) when available — they emit the UI events the components listen for.

10. Docs MCP (recommended)

claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp

Use it to confirm prop names, event signatures, theme tokens, or error meanings before writing non-obvious code.

11. Visual Builder — not available for Angular

The dashboard's Visual Builder export ships ZIPs for React / React Native / iOS / Android / Flutter — there is no Angular emitter. On an Angular project the dispatcher auto-routes to the code-driven path (sets customize=code), skips the Visually-vs-In-code prompt, and continues with this skill + cometchat-angular-{components,placement,patterns,theming}. If a stale customize=visual carried over from another project, the dispatcher overwrites it to code (a builder ... --platform angular call would be rejected at the CLI). Theming is via CSS variables (§7), not a builder.

Skill routing reference