cometchat-migrate-from-getstream

Ground truth: the STREAM side (what to look for) is baked in references/inventory.md + references/feature-map.md — confirm each hit by reading the user's code. The COMETCHAT side is never from memory: symbols come from the target family's skills + catalog, feature existence from that family's features.json, signatures from the docs via the family's -core/references/docs-map.md (Docs MCP first — RULES.md → Fetch discipline). REST pages live under DOCS_BASE = https://www.cometchat.com/docs.

Companion skills (read first)

• cometchat-<family>-core — the init → login → render the migrated app lands on. <family> is resolved in step 1; this skill ASSUMES that core and never restates its code.
• cometchat-<family>-components / -features / -calls / -push / -customization — pulled in only for the Stream features the inventory finds.

Use this skill when

The user asks to move an app off Stream: "migrate my app from GetStream/Stream to CometChat", "replace Stream Chat", "switch to CometChat", or "migrate my app to CometChat" when npx @cometchat/skills detect --json reports migrate_from with vendor getstream. Sendbird apps → cometchat-migrate-from-sendbird. An app with BOTH vendors: run both skills, one after the other, into one report.

The single-prompt contract (read before step 1)

The migration request IS the approval (RULES.md → Competitor migration). Run every step below to the end in this one turn:

• Do not stop to ask. No onboarding plan/approve gate, no clarification questions. Where a companion skill would ask, take the default written here, and record it under Defaults taken in the report.
• Safety net instead of questions: in a git repo, first git switch -c cometchat-migration (carries any uncommitted work along; mention that in the report). Never commit, push, or rewrite history. No git → proceed and say so in the report.
• Removing Stream is the requested outcome — RULES.md's append-never-replace does not protect Stream code. It still protects everything else: touch non-chat code only to rewire it.
• Credentials: never ask, never provision. Reuse .cometchat/config.json or existing CometChat env values if present; otherwise write the family's env/settings file with clearly-named placeholders so the build still compiles, and make "add your CometChat credentials" action item #1. Never write a real key into a git-tracked file: check git ls-files <file> first. If the file is tracked, put real values in the untracked local variant the framework reads (Vite/Next .env.local, Android local.properties, …) and keep placeholders in the tracked file. Adding a tracked file to .gitignore does NOT untrack it. The server's REST API key only ever goes into an untracked file or the hosting env.
• Only three STOPs: (1) no Stream usage found → say so and hand to cometchat; (2) the app's platform has no family in this pack (Vue, Unity, .NET, …) → deliver the inventory + feature map as the report, change nothing; (3) the build was already failing before you started → record the pre-existing errors, migrate anyway, and label them as pre-existing.

Migration workflow (BAKED — do every step, in order)

Every step applies to every app, however small: a 3-file sample still has vendor users and history, so steps 4 (toCometChatId) and 8 (data script) are ALWAYS delivered. Only a step whose subject truly doesn't exist (no server → step 7) may be skipped, and it's listed under Defaults taken as skipped: <why>. A silent skip is a failed migration.

1. Detect. npx @cometchat/skills detect --json → framework, android_variant, existing_cometchat, migrate_from. Resolve <family> exactly like the router (peers.yaml dir_prefix; per-platform targets in references/inventory.md §Target family). Monorepo: migrate every package that uses Stream, including the server that mints tokens. existing_cometchat: true + Stream still present = a half-finished migration: resume it, don't redo it. Read .cometchat/config.json if it exists: its appId/region/authKey are THE credentials. Write them into the family's untracked env/settings file (single-prompt contract), never ask. Before editing anything, run the app's build once and record whether it passed.
2. Inventory — the usage ledger. Grep per references/inventory.md (packages, imports, client creation, connectUser, SDK components, event subscriptions, channel queries, custom attachments, push devices, Video, Feeds, env vars, server tokens, webhooks, tests/mocks). Record every hit as file:line → what it does. Classify the app: UI SDK mode (Stream's React/Angular/RN/Flutter/iOS/Android UI components render the chat) → the family's CometChat UI Kit replaces them; client mode (own UI on the low-level client: stream-chat, stream_chat, StreamChat/ChatClient, stream-chat-android-client) → KEEP the app's UI and port its data layer to the family's CometChat Chat SDK; mixed → both.
3. Feature map. For every Stream feature the ledger shows, look up its row in references/feature-map.md, then check the listed CometChat id in the TARGET family's features.json. Present → migrate. Absent → check BOTH levels — UI Kit (search_cometchat_docs "<feature> <platform> ui kit") AND Chat SDK/REST (… SDK); documented at either → migrate (no UI Kit drop-in is NOT unsupported), built with the SDK method in the app's own UI (RULES.md → UI Kit first, SDK fallback). Mark UNSUPPORTED only when NEITHER has it — and an empty MCP search is NOT proof: follow the verification ladder (re-query with CometChat vocabulary → live-fetch the likely docs page → cross-check the family CATALOG) in references/feature-map.md §Deciding unsupported, before any REMOVE. Never call a feature unsupported from memory or invent an API; if it truly can't be verified, KEEP it as needs-verification. Every UNSUPPORTED row needs evidence in the report — the features.json result + the exact UI Kit AND SDK queries you ran.
4. Install CometChat and wire the core per cometchat-<family>-core (its install, initFromSettings, login gate, render order, env file). Identity: the CometChat UID is the app's existing Stream user ID passed through ONE shared toCometChatId() (references/concept-map.md §IDs). The GUID is the channel cid (type:id) through the same helper. The client login, the server token endpoint AND the data script all call the SAME toCometChatId() — put it in a shared client module (src/cometchat/ids.ts; native → §Native platforms) the login imports, and copy that body verbatim into the data script. Route the current-user id through it at login even when the Stream id already looks valid (it's a no-op then); confining toCometChatId to the data script is the #1 Stream migration miss and imports users under UIDs the app never logs in as (references/concept-map.md §IDs). Login: the app minted Stream user tokens on a server (createToken) or used a tokenProvider → migrate that endpoint (step 7) and use the auth-token login; the app used devToken() → Auth Key login (dev only) + an action item to switch to tokens before production. Keep every identity source, in the same order: whatever decides the current user today (URL params, env vars like VITE_USER_ID, the auth provider, a stored ID, a demo fallback) still decides it after the migration. Only the Stream-token-derived path becomes the CometChat auth token. Dropping one silently logs a configured deployment in as someone else. Returning users: the app already persists who is signed in (localStorage, keychain, prefs, a cookie) from the vendor era. Gate the chat on CometChat's logged-in user, NOT that cached ID. On start, a stored ID with no CometChat session → run the same login path before rendering any CometChat component; if that fails → the sign-in screen. Otherwise every user who was signed in before the upgrade lands on a broken chat. No UI Kit family for this app? A headless / vanilla-JS app that draws its own UI on the stream-chat client (no framework the pack ships a UI Kit for) has no -core to wire — do NOT stop. Install the CometChat Chat SDK for the platform (web → @cometchat/chat-sdk-javascript) and migrate the data layer straight onto it, taking every method from the SDK docs (/sdk/<platform>/*). Keep the app's own UI; there is no UI Kit to install. This is client/SDK mode with no framework core — the concept map's SDK/client-mode section still applies.
5. Replace usage, file by file, using references/concept-map.md: client/connectUser → CometChat init/login; ChannelList → conversations; channel (Channel/Window/MessageList/MessageInput/Thread) → message pane; member-based distinct channels → user conversations; client.on(...)/channel.on(...) → listeners (remove them on unmount); attachments/threads/reactions → the core + -features skill; theme/CSS variables/i18n → -customization; Stream Video → -calls (or the headless calls peer); push devices → -push. Remove each Stream import as you replace its last use. Both modes fetch from docs only: UI Kit component props AND SDK method signatures come from the live docs (the family core's docs-map.md), verified against the catalog — never written from memory or ported from the vendor's API shape.
6. Remove unsupported features FULLY. For each UNSUPPORTED row: delete the feature's code path, its UI entry points (buttons, menu items, slash commands, routes, screens, settings toggles), state/stores, types, hooks, assets, tests, env vars, server endpoints and dependencies — no dead buttons, no commented-out blocks, no feature flags left on. Keep the surrounding screen working. Activity Feeds has no CometChat equivalent: feed screens, activity writers, follow buttons and the feed server calls all go, and are listed. Log each one for the report: feature · what it did · files changed · what users lose · the closest CometChat alternative (if any).
7. Server side. Replace Stream token minting (createToken, upsertUser on sign-up) with a CometChat auth-token endpoint (REST: create the user if missing, then create an auth token — /rest-api/auth-tokens, REST API key from server env only). Map Stream webhooks (verifyWebhook, x-signature) to CometChat webhooks (/rest-api/management-apis/webhooks/overview); before-message-send hooks, custom-command endpoints and SQS/SNS without an equivalent are REMOVED + listed. Replace other server-client calls with CometChat REST, or remove + list them.
8. Data migration script — write it, then run the import for the user. Generate scripts/cometchat-migration/ per references/data-migration.md: export users, channels, members and messages with the Stream server client → transform with the same toCometChatId() → import through the CometChat Data Import API. When the code migration is done, tell the user the data-import script is ready and ask for the credentials it needs — the source keys (STREAM_API_KEY, STREAM_API_SECRET) and the CometChat App ID, Region and full-access REST API key. (Asking for these is the ONE question the single-prompt contract allows; everything else still takes the documented default.) As soon as the user provides them, RUN the import yourself from env vars — never write the secrets into a repo file: a --dry-run first (show the users / channels / members / messages counts), then the real import, then report what landed and what failed. Only messages within CometChat's 6-month retention window import — tell the user to reach out to CometChat to import messages older than 6 months. If the user does not share credentials, leave running the script as an action item.
9. Uninstall Stream. Remove every Stream dependency (package.json + regenerate the lockfile, Podfile/SPM, Gradle, pubspec), CSS imports (stream-chat-react/dist/css/…, @stream-io/stream-chat-css), i18n setup, env vars, native config, and CI secrets references. Remove Stream-only peer dependencies (offline SQLite, audio recorder, …) only when nothing else imports them. react-native-reanimated, react-native-gesture-handler and react-native-svg are usually shared: keep those. Re-run the package manager install. On iOS/SPM the ROOT manifest counts too: a vendored-SDK repo declares the vendor in its own Package.swift/*.podspec at the repo root, not just in the app's .xcodeproj — remove the dependency there AND delete any vendored Framework/*.xcframework, or the vendor package is still declared after every call site is gone. Update the app's OWN docs (README, setup/deploy guides, .env.example): setup steps, env var names and screenshots captions that describe Stream now describe CometChat. Rename Stream-named identifiers (getstreamUserId → userId).
10. Verify (§Verify it works). Fix every build error you introduced. Don't run live tests unless asked (RULES.md → Verification scope).
11. Report. Write COMETCHAT_MIGRATION.md at the repo root from references/report-template.md, then END your reply with its two lists pasted in full: Removed — not available in CometChat and Your action items. This final list is the deliverable the user asked for; never skip it, even if nothing was removed (say "none").

Common pitfalls

• Accessibility is never a "missing feature". Stream-provided skip links, focus management, live regions and keyboard shortcuts are plain HTML/ARIA/host code. Re-create them in the app against the new CometChat layout, and never list them as Removed. Losing them is a regression, not an honest removal.
• The provider swap moves wrapper elements. CometChatProvider (and, on web, CometChatErrorBoundary) render wrapper elements exactly where the vendor's provider sat. If they now wrap the app's own shell/header, each wrapper needs a height in the chain, or the chat renders at 0px while the build passes. Follow the core's layout reference, and check the chain from the root element down to the conversation list.
• IDs that CometChat rejects or merges. UIDs/GUIDs are alpha-dash (a-z 0-9 - _), max 100 characters, and lowercased. Stream cids contain :, member-based channel IDs start with !members-, and user IDs can contain @ or .. Sanitize with one deterministic function everywhere, and always feed it the full cid, so messaging:general and team:general stay distinct.
• 1:1 chats are not groups. A member-based channel (!members-… ID, created from exactly two members) becomes a CometChat user conversation, not a two-person group.
• Livestream channels and large groups. CometChat sends receipts and typing indicators only in groups up to 300 members (100,000 without them). List that as a behavior change for big channels.
• Leftover subscriptions. Every client.on(...)/channel.on(...)/useChatContext event path needs a CometChat listener that is also removed on unmount/dispose. Missing removals cause duplicate messages.
• Custom attachments and extraData. Stream custom fields ride on users, channels and messages; move them into CometChat metadata/custom messages, or they silently disappear.
• Half-removed features. Deleting the API call but leaving the slash command, button or route is a dead end (RULES.md → Default-on affordances). Remove the entry point too.
• Shared native dependencies. Removing a Stream peer dependency the app also uses (Reanimated, gesture handler, SVG, image picker) breaks unrelated screens. Grep for other importers first.
• Never delete non-Stream code that just shares a file with Stream code. Rewire it.

Native platforms (Android · iOS · Flutter) — NOT done until the platform build passes

Native builds (Android/iOS/Flutter) have extra REQUIRED steps beyond editing code — bump the sample toolchain to the -core build floors, add the kit dep AND wire initFromSettings in the app entry, port toCometChatId to the client language, edit .pbxproj/.xcscheme as structured build graphs (never a text scrub), and RUN the platform build. A native migration is NOT done until you have followed references/native-build.md in full — open it and work through every step; it is mandatory, not optional.

Verify it works

• The app builds/type-checks with the family's normal command (the core skill's "Verify it works").
• RUN it and read the logs — a compile is NOT a working app (do this; don't skip). When you're done implementing, START the app and confirm it LOADS with the chat surface rendered and NO errors: web → the dev server (or build + preview), open it, watch the browser console + the dev-server terminal; native → the platform run + logcat / Xcode console / flutter logs. Fix EVERY runtime error you introduced before declaring done — a Cannot read properties of undefined from a half-migrated reference, or an SDK enum/class read at module-load before the SDK is ready, is a migration bug, not the user's problem (hand off to cometchat-<family>-troubleshooting for symptom → fix). If the app genuinely can't be started here (no dev env / needs a device), SAY SO and give the user the exact run command + what to watch for — never silently skip this.
• Zero Stream residue — run exactly this, over ALL file types (docs included): grep -rIilE 'stream-chat|stream_chat|@stream-io|getstream|StreamChat|StreamVideo' . --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build --exclude-dir=.claude --exclude-dir=Pods --exclude-dir=.dart_tool --exclude-dir=.gradle | grep -vE 'COMETCHAT_MIGRATION.md|scripts/cometchat-migration' → must print nothing (repeated --exclude-dir= flags on purpose: a {a,b} brace list is rejected by the coding agent's command-permission parser, so the check silently never runs). The ONE allowed mention is a single provenance comment above toCometChatId(); code identifiers, README lines and env names are residue, not "expected". This includes a "migrated from " line in the README or any doc you write — a provenance note reads as helpful and is still residue; the migration report is where that belongs, and it is already exempt. Rewrite the app's own README so it describes CometChat, naming the vendor nowhere. The same goes for every other doc the repo ships — CHANGELOG.md, docs/, changelogs/, a vendored SDK's own release notes: if a file is not the migration report, it must not name the vendor. Delete the ones that document the vendor's product rather than your app.
• scripts/cometchat-migration/migrate.mjs + README.md exist — even for a demo/sample app with no data of its own (it is for the user's real data; step 8 is never skipped).
• Every CometChat symbol you emitted exists in the family catalog. Every migrated feature is in features.json or the docs. Every UNSUPPORTED item is in the report's Removed list with its files.
• The server token endpoint, the client login and the data script all call the same toCometChatId() — from a shared client module, and at login even for already-valid ids (not only inside the data script).
• Runtime shape, statically checked: every element from the root to the conversation list has a height (wrappers included). A user who was signed in before the migration is logged in to CometChat again before the chat renders. No real secret sits in a git-tracked file (git ls-files each file you wrote credentials to).