Cometchat Angular V5 Core

Ground truth: @cometchat/chat-uikit-angular@^5 + @cometchat/chat-sdk-javascript@^4, symbols verified across 5.1.0–5.2.0 / 4.1.13–4.2.0 (unchanged set; catalog verifiedCompatibleRange). This file is the THIN map loaded every run; deep detail lives in references/*, loaded ONLY when the task needs it.

Use this skill when

Adding CometChat to an Angular app, or you need the setup every other Angular v5 skill assumes: install, credentials, init→login→render ordering, and the component map.

Prerequisites & install

The three Angular rules that break everything else

Read these first. Each produces code that compiles, shows no error, and does not work.

1. Every component must be in imports: []. The kit ships standalone components. Use <cometchat-conversations> in a template without importing CometChatConversationsComponent into that component's imports array and Angular renders nothing — no error, no warning, blank space. This is the single most common failure.
2. Config lives in src/environments/environment.ts, NOT .env. Angular resolves it at build time via file replacement. Any .env instruction is wrong here.
3. Class name ≠ selector ≠ docs title. CometChatConversationsComponent (import) · <cometchat-conversations> (template) · "Conversations" (docs). All three are different; use the right one in the right place.

Install

npm install @cometchat/chat-uikit-angular@^5 @cometchat/chat-sdk-javascript@^4 @cometchat/cards-angular@^1 dompurify@^3

Calls only (optional): npm install @cometchat/calls-sdk-javascript@^5

⚠️ Angular 22 fails to install. The kit's peer range is @angular/core >=17.0.0 <22.0.0, so npm install on Angular 22 hard-fails with ERESOLVE. Scaffold a new app with npx -y @angular/cli@21 new <app>. CometChat's stated policy is that 18+ is supported, so this range is expected to widen in a future kit release — until it ships, 22 does not work. Angular 17 works but is undocumented.

angular.json needs three changes under projects.<app>.architect.build — the stylesheet, the icon assets, and the production budgets.

styles — the kit stylesheet must come FIRST, before your own:

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

⚠️ Order decides, and failing it is SILENT — the kit re-declares tokens under [data-theme="dark"] at your :root's specificity, so appending the kit file makes it win and your brand colors vanish without error. Detail: references/theming.md.

assets — the kit ships ~300 SVG icons under src/lib/assets (the glob copies them all; count is not load-bearing):

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

Production budgets — raise them or ng build HARD-FAILS. The kit + Chat SDK is ~4.2 MB against a stock 1 MB error budget, so the DEFAULT ng build exits non-zero while ng serve is fine. Raise budgets + set allowedCommonJsDependencies: references/dependencies.md.

⚠️ Miss the assets entry and icons are broken throughout the kit (send/attach/emoji, call controls, menus) — nothing errors, it just reads as a theming problem. The single most commonly missed setup step in Angular. ⚠️ Do not @import the kit's css-variables.css in a .scss/.css file — the package's exports map does not expose that path and the build fails. The full node_modules/... path in angular.json bypasses it.

Full dependency table: references/dependencies.md.

Setup & credentials (essentials — full detail: references/setup-credentials.md)

Three values: App ID, Region, Auth Key. When they are missing, OFFER both paths and default to the fetch — "I can fetch them by logging into your CometChat dashboard, or you can paste them manually" — and never end the build with a "add credentials yourself" TODO.

// src/environments/environment.ts
export const environment = {
  production: false,
  cometchat: { appId: 'APP_ID', region: 'REGION', authKey: 'AUTH_KEY' },
};

A fourth value you must ASK for: the login UID. The app logs in as somebody the moment it opens, and only the developer knows who that should be. Ask — do not pick one silently:

"Which user should the app log in as on startup? You'll find your UIDs under Dashboard → your app → Users. If this is a fresh app I can create cometchat-uid-1 for you and log in as that."

cometchat-uid-1 is the docs sample, not a promise about this app — on an app whose sample users were never seeded, login() fails and the screen stays blank with no visible error. Never hardcode it and move on; if the developer has no UID, use the create-if-missing ensureDevUser() (references/lifecycle.md).

Create environment.prod.ts with the same shape and wire fileReplacements in angular.json. The Auth Key is dev-only — production mints an auth token server-side and calls loginWithAuthToken. See references/setup-credentials.md.

Integration ordering (BAKED — invariant)

init() must resolve BEFORE login(), and login() before any kit component renders. Out of order, components mount with no session and render empty.

In Angular this is an app initializer, not a component effect:

// src/main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { CometChatUIKit } from '@cometchat/chat-uikit-angular';
import { environment } from './environments/environment';
// Angular 20+ scaffolds `src/app/app.ts` exporting `App`; 17-19 scaffold `app.component.ts`
// exporting `AppComponent`. Use whichever YOUR app has (wrong one → "Could not resolve …").
import { App } from './app/app';                 // Angular 20+ (CLI 21 default)
// import { AppComponent } from './app/app.component';   // Angular 17-19
import { appConfig } from './app/app.config';

const { appId, region, authKey } = environment.cometchat;
// authKey is DEV-only: prod ships it empty + logs in with a server token — so require it
// only in dev, else every prod build throws behind a green `ng build`.
if (!appId || !region) {
  throw new Error('CometChat appId/region empty — check src/environments/environment*.ts.');
}
if (!environment.production && !authKey) {
  throw new Error('CometChat authKey empty — dev login needs it (production uses an auth token).');
}

// `cometchat-uid-1` is the docs SAMPLE, not a guarantee this app has it — a missing UID renders a
// blank screen. Use a real UID from Dashboard → Users, or ensureDevUser() (references/lifecycle.md).
const uid = 'cometchat-uid-1';

// Prod only: YOUR backend mints this user's auth token (endpoint shape: cometchat-angular-v5-production).
async function fetchAuthToken(): Promise<string> {
  const res = await fetch('/api/cometchat-token', { credentials: 'include' });
  if (!res.ok) throw new Error(`CometChat token endpoint: HTTP ${res.status}`);
  return ((await res.json()) as { authToken: string }).authToken;
}

// initFromSettings (NOT the classic builder init) so integrationSource="ai-agent" propagates for
// telemetry attribution, and routes the Calls SDK too.
// Bootstrap the app in `finally` so it ALWAYS mounts: a failed init/login (empty prod authKey, a wrong
// UID, a network blip) must leave CHAT degraded, never the WHOLE Angular app blank behind a green build.
(async () => {
  try {
    await CometChatUIKit.initFromSettings({
      appId,
      region,
      credentials: { authKey },                              // dev only — empty in prod
      chatSDK: { presenceSubscription: { type: 'ALL_USERS' } },
    });
    await (environment.production
      ? CometChatUIKit.loginWithAuthToken(await fetchAuthToken())  // prod: authKey stays server-side
      : CometChatUIKit.login(uid));                                // dev: Auth-Key login
  } catch (e) {
    console.error('CometChat init/login failed', e);
  } finally {
    bootstrapApplication(App, appConfig).catch((err) => console.error(err));
  }
})();

Guarded login, ensureDevUser (create-if-missing for a dev start), provideAppInitializer, route guards, and the loggedInUser$ Observable: references/lifecycle.md.

Docs first for the API — the installed kit for BEHAVIOUR the docs omit

What exists and what it is called comes from the docs. Fetch the component's page (references/docs-map.md → DOCS_BASE + path + .md); read its AI Integration Quick Reference first. Do not invent an API from the type declarations — they expose internal-only names and members with no defined behaviour.

But reading the shipped bundle IS correct when the docs state a prop and not its semantics (e.g. attachmentOptions — does yours append or replace? it appends; messagesRequestBuilder — override or merge?). When behaviour is load-bearing and undocumented, verify it in node_modules/@cometchat/chat-uikit-angular/fesm2022/*.mjs, then (1) say in your summary you verified against the installed kit, and (2) report it as a docs gap.

Full methodology + the worked examples — see references/docs-map.md § "Docs first for the API".

Component / API map (BAKED closed list)

Exported class → template selector. Anything not here, look up via references/docs-map.md — do not guess.

Non-component exports you will need: CometChatUIKit (init/login), UIKitSettingsBuilder, ChatStateService (active chat state), CometChatUIKitConstants, CometChatLocalize, ThemeService.

Naming exception: the AI-assistant exports carry no Component suffix — CometChatAIAssistantChat, not …ChatComponent.