[oliverlaz]

Goal

Ticket: https://linear.app/stream/issue/REACT-1162

We migrated two demo apps from v14 to 15.0.0-rc.3 (stream-chat@10.0.0-rc.26) using only ai-docs/ai-migration-v14-v15.md and the stream-chat-js v10-breaking-changes.md, and logged every place the guides fell short. The findings and the migrated code are in GetStream/website-react-examples#138. Every compile error had an answer in the guides; the gaps are UI states that compile but behave differently, mostly because ChatView unmounts the inactive view, plus a few type-level holes. This PR fixes them in the guide. Docs only, and it describes the current rc API.

Implementation details

Each claim was checked against the source in this repo, and every new or changed snippet compiles against the installed stream-chat-react@15.0.0-rc.3 / stream-chat@10.0.0-rc.26 (strict, noImplicitReturns, noUnusedLocals).

• Section 3: says the inactive ChatView view unmounts. Only the slot bindings survive; state, refs and effects inside a view start over on every switch.
• Section 6, useOpenFirstChannel: the useRef guard reset on remount, so returning from the threads view re-opened the first channel over the one the user had open. The hook now guards on useWorkspaceNavigation().openChannels.length === 0. It also notes where to call it (the channels view, not an always-rendered ChatView child, where openChannels is empty in the threads view) and that it re-opens when nothing is open.
• Section 6, paginator example: the paginator is created and registered once, above ChatView (useChannelPaginator), so it is not re-created and re-queried on every view switch.
• Section 4, "Without ChatView": the override list is split into always / threads / default headers. It adds isThreadDismissable (the default ThreadHeader close button needs it, and its default is () => false), isChannelDismissable with closeChannel, and canGoBack with goBack. The example now overrides isThreadDismissable.
• Section 5: a concrete stale-state example (useState(channel.data?.custom?.name) keeps the previous channel name) and its fix.
• Section 9: reading event.user from the typing slice behind an EventPayload<'typing.start'> type guard (Event is a union, so the unguarded read fails with TS2339), plus a note that the guard can go if stream-chat narrows the slice type.
• Section 19: a ready-to-run grep for the removed classes over *.css / *.scss / *.sass / *.less, which also matches them inside combinators (e.g. .x + .str-chat__main-panel) and skips .str-chat__main-panel-inner and .str-chat__thread-container, which still exist.
• Silent-break table: new rows for the channel resetting after a view switch, the missing thread close button without ChatView, and state seeded from the channel going stale; the CSS row now points at the grep.
• Smaller fixes:
  • Sections 7 and 10: warn that TypeScript's "Did you mean ThreadHead?" for a stale ThreadHeader key points at the parent-message slot.
  • Section 7: useCloseThread takes a WorkspaceNavigationTriggerEvent, narrower than v14's BaseSyntheticEvent.
  • Section 10: opens with "if your custom message UI calls getMessageActions()" so those apps know to switch to useUserRole.
  • Section 13: new subsection on setMessageComposerSetupFunction being deprecated in favour of client.config.setSetupFunction('messageComposer', ...).
  • Section 18: the flow "string not in the key map, so app-owned, so asDynamicKey".
  • Section 6: a custom ChannelListItemUI receives the computed active prop.
  • Section 1: reads the stream-chat peer range from the installed package.json instead of a hard-coded rc, and lists the stream-chat type changes that are usually the first errors (ChannelSort to SortParamRequest[], queryChannels raw vs queryChannelsAndHydrate, queryUsers({ payload })).
• Links: the three links to stream-chat-js master/ai-docs/v10-breaking-changes.md returned 404, because the file lives on release-v10 (docs: consolidate v10 breaking changes into ai-docs stream-chat-js#1919 merged there). They now point at release-v10 and use that guide's explicit anchors.

UI Changes

None, documentation only.

Summary by CodeRabbit

• Documentation
  • Updated the v14-to-v15 migration guide with guidance on channel state during view changes and workspace navigation, thread-header dismissal, and custom channel-list setup.
  • Revised examples for pagination and channel opening, and clarified compatibility guidance, typing-event handling, CSS search, and references to earlier migration documentation.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 48d8762c-0566-4317-9139-03e722712310

Commits

Reviewing files that changed from the base of the PR and between fc8795a and ffcc9c0.

Files selected for processing: 1

• ai-docs/ai-migration-v14-v15.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Walkthrough

The v14-to-v15 migration guide adds guidance on view lifecycle, channel navigation, and channel-list state. It also updates API and type migration notes, compatibility references, translation guidance, and CSS troubleshooting instructions.

Changes: Migration guide

Layer / File(s)	Summary
View lifecycle and channel navigation ai-docs/ai-migration-v14-v15.md	Explains how ChatView unmounts inactive views and how local state and paginators behave on return. Updates navigation overrides, channel-name draft handling, and first-channel initialization examples.
API and migration clarifications ai-docs/ai-migration-v14-v15.md	Updates stream-chat compatibility guidance and clarifies typing events, thread slots, message actions, composer setup, translations, and CSS troubleshooting. Also updates migration-note references and channel-list item guidance.

Priority: Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Possibly related PRs

• GetStream/stream-chat-react#3328: Changes v15 runtime behavior around ChatView, workspace navigation, pagination, and APIs covered by the guide.
• GetStream/stream-chat-react#3342: Changes pagination and typing behavior documented in the guide.
• GetStream/stream-chat-react#3329: Creates the v14-to-v15 migration guide that this PR updates.

Suggested reviewers: martincupela, nikolagorannaumovski

Merge Risk: Minimal · up to ffcc9

This documentation-only update clarifies migration guidance and examples, and no concrete defect remains. There is no runtime impact and no merge-blocking risk.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly summarizes the main change: updating the AI migration documentation to address gaps found while migrating website demo apps.
Description check		The description includes the goal, implementation details, and UI changes sections. It explains the migration findings, documentation updates, validation approach, and confirms that no UI changes were…
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description includes the goal, implementation details, and UI changes sections. It explains the migration findings, documentation updates, validation approach, and confirms that no UI changes were made.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.66%. Comparing base (3c8b30a) to head (ffcc9c0).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3356   +/-   ##
=======================================
  Coverage   88.66%   88.66%           
=======================================
  Files         563      563           
  Lines       17139    17139           
  Branches     5246     5246           
=======================================
  Hits        15196    15196           
  Misses       1943     1943           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.