Companion skills (read first)
cometchat-ios-coredescribes the v5 target state. This skill is the RECONCILIATION path to it. Build from the official guide — fetch/ui-kit/ios/upgrading-from-v4viacometchat-ios-core/references/docs-map.md— then apply the deltas below.
Use this skill when
An existing v4 integration must move to v5, or a build breaks with cannot find 'CometChatConversationsWithMessages' in scope after an upgrade.
The one change that dominates the migration
v4's composite components are gone. CometChatMessages, CometChatUsersWithMessages, CometChatGroupsWithMessages, CometChatConversationsWithMessages do not exist in v5, and neither do the configuration objects that fed them (MessageHeaderConfiguration, MessageListConfiguration, MessageComposerConfiguration).
That is not a rename — it is an inversion of ownership. v4 gave you one screen that did everything; v5 gives you three components and expects you to own the screen and the navigation. Every place the old code pushed a composite becomes a view controller you write, composed per cometchat-ios-core's golden path, with its five layout rules applied.
Budget for this honestly: it is the bulk of the work, and it is a design change in the host app, not a search-and-replace.
Then the mechanical deltas
- Theming was replaced. v4's theme objects give way to
CometChatTheme's static colours plus per-component style objects. Re-derive the brand from the theme rather than porting v4 style code —cometchat-ios-customization. - Setter vs property split. Several v4 setters are v5 properties: styles (
avatarStyle,badgeStyle,receiptStyle,statusIndicatorStyle,typingIndicatorStyle),onSearchClick,onSelectedItemProceed, the call-button click handlers. - Renames to expect:
set(usersRequestBuilder:)→set(userRequestBuilder:)·set(subtitleView:)→set(subtitle:)andset(trailView:)→set(trailingView:)on Users/Groups only (Conversations and GroupMembers keep the old spelling) ·set(sessionID:)→set(sessionId:)·set(callSettingBuilder:)→set(callSettingsBuilder:)·set(onDeclineClick:)→set(onCancelClick:)·set(parentMessage:)→set(parentMessageId:)on the list and composer, though the thread header still takesset(parentMessage:). - Dependencies. v5 is SPM-only (CocoaPods is winding down) and pins exactly: kit 5.1.22 / SDK 4.1.7 / Calls 5.0.3, all added by hand.
Method
Upgrade the dependency first and let the compiler enumerate the work — the errors are the migration checklist. Fix composites first (they cascade), then styling, then the renames. Do it additively: the host app's navigation, auth and design system stay theirs.
Gotchas
- Never mix majors. A half-migrated project with both v4 and v5 symbols will not build.
- Check every symbol against
catalogs/ios-v5.jsonbefore porting it — if it is absent, it is gone, and a v5 doc page mentioning it is not evidence it exists.
Verify it works
The project builds with no v4 symbols remaining; every screen that was a composite is now a composed screen that renders full-size, keyboard-avoids and navigates back; theming looks intentional rather than half-ported.