cometchat-angular-v5-migration
Upgrade an Angular app from CometChat UI Kit v4 → v5 (`@cometchat/chat-uikit-angular` ^4 → ^5). Reads the repo's CometChat usage, applies the breaking-change map (deps, composite components removed, bare→Component renames, CometChatThemeService → CSS variables, event inputs → Outputs, DataSource → composition, localization renames), fetches the exhaustive guide, and verifies the build. Triggers: 'upgrade my v4 uikit to v5', 'migrate cometchat angular v4 to v5', 'upgrade @cometchat/chat-uikit-angular to v5', 'cometchat angular v4 to v5', 'bump cometchat angular uikit'.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- cometchat-angular-v5-migration
- license
- MIT
- metadata
- { "tags": "cometchat angular migration upgrade v4 v5 uikit", "author": "CometChat", "version": "1.0.0" }
- description
- Upgrade an Angular app from CometChat UI Kit v4 → v5 (`@cometchat/chat-uikit-angular` ^4 → ^5). Reads the repo's CometChat usage, applies the breaking-change map (deps, composite components removed, bare→Component renames, CometChatThemeService → CSS variables, event inputs → Outputs, DataSource → composition, localization renames), fetches the exhaustive guide, and verifies the build. Triggers: 'upgrade my v4 uikit to v5', 'migrate cometchat angular v4 to v5', 'upgrade @cometchat/chat-uikit-angular to v5', 'cometchat angular v4 to v5', 'bump cometchat angular uikit'.
- compatibility
- Angular 17-21; FROM @cometchat/chat-uikit-angular ^4 (4.3.36) → ^5 (5.1.0–5.2.2 verified); @cometchat/chat-sdk-javascript ^4.1.13 (peer; 5.2.x needs ^4.2.0); @cometchat/cards-angular ^1.0.0 (new peer, undocumented in the official guide); @cometchat/uikit-elements/-resources/-shared removed
02 资源文件 1
- 参考文档references/migration-guide.md19.4 KB
03 SKILL.md 正文
Ground truth: migrates an Angular app FROM
@cometchat/chat-uikit-angular@4TO@5. v5 target symbols are catalog-verified vs installed 5.1.0; the v4→v5 breaking-change map is BAKED inreferences/migration-guide.md(distilled from the official "Upgrading From V4" guide + a real v4.3.36→v5.1.0 export diff — 146 genuine removals, 33 bare→Componentrenames, kept separate). The exhaustive per-component prop table is FETCHED fromcometchat-angular-v5-components/references/catalog.md+ the docs.mdtwins. APPEND/transform the user's code — never wipe it; work on a branch and confirm before bulk edits (RULES.md).
Companion skills (read first)
cometchat-angular-v5-core— the v5 init/login/render the migrated app lands on. This skill ASSUMES it.cometchat-angular-v5-components— the v5 component catalog (the target names + real inputs/outputs).cometchat-angular-v5-placement— how to rebuild a v4 composite from v5 modules (§2 of the migration guide points here per composite).
Use this skill when
"upgrade my v4 UI Kit to v5", "migrate CometChat Angular v4→v5", "bump @cometchat/chat-uikit-angular to v5". Precondition: the project currently has @cometchat/chat-uikit-angular@4.
Migration workflow (BAKED)
- Detect the starting point. Confirm
package.jsonhas@cometchat/chat-uikit-angular@4(already@5→ STOP, nothing to migrate). Note whether the app uses composite components (...WithMessages/...WithDetails),CometChatThemeService,*Styleinputs,DataSource/ChatConfigurator, or custom localization keys — each drives a later step. Work on a branch; transform in place, never delete the user's code. - Update dependencies.
npm install @cometchat/chat-uikit-angular@5 @cometchat/chat-sdk-javascript@^4.1.13 @cometchat/cards-angular@^1.0.0thennpm uninstall @cometchat/uikit-elements @cometchat/uikit-resources @cometchat/uikit-shared.@cometchat/cards-angularis a genuine new 5.1.0 peer the official guide never mentions — install it or the build fails on a missing peer, not a CometChat error. - Scan the repo for v4 usage. Grep for every symbol in
references/migration-guide.md§2 (composites, no-equivalent standalones,DataSource/decorators, the ~35*Styleobjects) and §2b (the 33 bare-name renames) — produce the concrete change list before editing anything. A bare name is not automatically "removed"; check §2b first. - Apply the breaking-change map (
references/migration-guide.md): §2/§2b symbol removals + renames, §3 theming (CometChatThemeService+*Style→ CSS variables + the realThemeService, not the official guide's own hand-rolledmatchMediaexample — see the warning in §3), §4 event-input → Output rename, §5DataSource/ChatConfigurator→MessageBubbleConfigServiceor "nothing, it's auto-rendered," §6 dropCUSTOM_ELEMENTS_SCHEMA+ convert to standalone, §7 optionalChatStateServiceadoption, §8 localization method renames. The baked map is a closed list, not a prop reference — FETCH the rest (RULES.md§ Fetch discipline; nevernode_modules/**/*.d.ts), routed fromcometchat-angular-v5-core/references/docs-map.md: the official guide{DOCS_BASE}/ui-kit/angular/customization/migration-guide.mdfor anything the map omits; a component's exact inputs/outputs/slots from its own.mdtwin (Angular has nomigration-property-changespage — there is no single prop-diff table); an SDK method for a capability with no v5 component ({SDK_DOCS_BASE}/sdk/javascript/groups-overview.mdet al.) — that is where the host-composed group surfaces in step 5 come from. - Rebuild every composite from modules. v5 has no composite components at all —
CometChatConversationsWithMessagesetc. must become a hand-stitched surface. Usecometchat-angular-v5-placement/references/core-surface.md(1:1) orcombined-app.md(tabbed) as the target shape, not a literal prop-for-prop port — the composite's configuration options (which v4 had many of) don't exist in v5; its behavior is what you're reproducing. - Verify. Build/typecheck passes; NO v4 symbols remain (grep
references/migration-guide.md§2's full list); every kit component is in its consumer'simports: []; the app renders after init→login resolves (cometchat-angular-v5-core/references/lifecycle.md). Reusecometchat-angular-v5-core"Verify it works".
Common pitfalls (BAKED)
- Porting the official guide's own theming example. It shows a hand-rolled
matchMedialistener for OS-follow — that predates the real v5 mechanism.ThemeService.initFromPreference()already does this; don't reintroduce v4-era manual theme-tracking code (§3). - Treating a bare v4 name as removed when it's only renamed. Check §2b (33 bare→
Componentrenames) before concluding a component is gone — most "missing" names are one word away from their v5 form. - Missing
@cometchat/cards-angular. Genuinely undocumented in the official migration guide; the install fails on a peer-dependency error that looks unrelated to the migration. - Forgetting
imports: []after droppingCUSTOM_ELEMENTS_SCHEMA. v4's schema tolerated unregistered elements; v5's standalone components render nothing, silently if omitted fromimports: []— the single most common v5 failure mode, and migrated code is exactly where it's missed (cometchat-angular-v5-core/SKILL.md). - Rebuilding a composite as a literal prop-for-prop port. v4 composites had large configuration surfaces (
*Styleobjects, callback inputs) with no v5 equivalent — port the behavior, not the configuration, usingcometchat-angular-v5-placement's real recipes as the target. - Assuming every
DataSourceDecoratorneedsMessageBubbleConfigService. Some were registering a built-in extension (polls, stickers, translation) — v5 auto-renders most of those once enabled in the dashboard, with nothing to register (cometchat-angular-v5-features/SKILL.md; verify againstneeds_stitchinginfeatures.angular-v5.json, never assume).
Verify it works
Build/typecheck is green; a repo-wide grep finds NO §2 v4 symbols (composites, CometChatThemeService, DataSource/ChatConfigurator, any *Style object, any bare §2b name unqualified); every kit component is in imports: []; the app renders once init→login resolves; migrated theming follows the OS via ThemeService, not a leftover matchMedia listener. Full per-component prop reference: cometchat-angular-v5-components/references/catalog.md + the docs .md twins.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.