docs: add AI migration guide and drop legacy stream-chat-css wiring#3129
Merged
docs: add AI migration guide and drop legacy stream-chat-css wiring#3129
Conversation
Adds ai-docs/ai-migration.md, a token-optimized execution guide for coding agents performing the v13 → v14 migration. Distills the 62 confirmed breaking changes from ai-docs/breaking-changes.md into ordered phases, rename lists, and code-level rewrites. Removes the superseded ai-docs/DEPRECATED_API_REMOVAL_PLAN.md.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3129 +/- ##
=======================================
Coverage 82.33% 82.33%
=======================================
Files 419 419
Lines 12269 12269
Branches 3950 3950
=======================================
Hits 10102 10102
Misses 2167 2167 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Instruct agents to verify against installed node_modules rather than relying on pretraining knowledge, which skews to v13 and frequently hallucinates removed APIs.
.d.ts types are emitted under dist/types/, not dist/ root. Update the three affected paths and remove the incorrect .d.cts reference (the SDK emits .d.ts only). Point at dist/es/ and dist/cjs/ for transpiled JS. Also remove ./dist/scss/* and ./scss/* from the package.json exports map — dist/scss/ is no longer emitted, so those exports were dead.
|
Size Change: 0 B Total Size: 624 kB ℹ️ View Unchanged
|
The SDK no longer depends on @stream-io/stream-chat-css — the package is absent from package.json and yarn.lock, and dist/ has no scss/, css/v2/, or assets/ directories. Removes the now-dead tooling around it: - scripts/copy-css.sh: not wired into the build script and unreferenced outside of stale docs. - scripts/merge-stream-chat-css-docs.sh: copies docs into ./docusaurus/docs/React, a directory that no longer exists in this repo. - .github/dependabot.yml: drop the @stream-io/stream-chat-css auto-bump entry since the package isn't installed. Also update CLAUDE.md to reflect the current 4-step build (build-translations, vite build, tsc, build-styling) and the single- source styling tree under src/styling/.
oliverlaz
changed the title
Four SDK-mismatch fixes surfaced by validating the guide against
node_modules/stream-chat-react/dist/types:
- Hook name: useMessageComposer → useMessageComposerController. The
former does not exist in v14. The human migration guide had the
correct name; the AI guide had a hallucination.
- usePinHandler v14 signature is (message) with no second arg;
notifications are published internally via useNotificationApi().
- FileIcon props: `size` is not removed, only retyped from number to
FileIconSize ('sm' | 'md' | 'lg' | 'xl'); new `sizeConfig` prop
exists. Only `big`, `sizeSmall`, `type` were removed.
- ModalGalleryProps: no `initialIndex`. Actual props are { items,
className?, modalClassName?, closeOnBackgroundClick? }.
Also recommend the /css/* alias over /dist/css/* for stylesheet
imports: package.json exports map aliases it, so consumers do not need
to depend on the internal dist/ layout.
Same four fixes applied to ai-migration.md, now also at source so the audit tracker matches the installed v14 SDK: - BC-008: useMessageComposer().initState(...) → useMessageComposerController().initState(...) (the former hook does not exist). Also correct the file ref to src/components/MessageActions/MessageActions.defaults.tsx:160. - BC-021: FileIconProps still exposes size (retyped to FileIconSize 'sm' | 'md' | 'lg' | 'xl') and adds sizeConfig; only big, sizeSmall, type were removed. - BC-025: ModalGallery no longer accepts initialIndex. Rename guidance now points consumers at Gallery + GalleryUI when a non-zero starting item is required. - BC-059: usePinHandler v14 signature is (message), not (message, notifications?). Notifications are published internally via useNotificationApi().
MartinCupela
approved these changes
Apr 17, 2026
… models
Add two short orienting subsections that name the replacement primitives
for pieces scattered across Phase 2 / Phase 5 / Phase 7:
- Notification system (end of Phase 2): useNotificationApi(),
NotificationList, useSystemNotifications() /
useReportLostConnectionSystemNotification(). Consolidates the mental
model behind MessageListNotifications / ConnectionStatus / get*Notification
removals.
- Gallery model (mid Phase 7): ModalGallery vs. Gallery vs. GalleryUI as
three distinct primitives, with a migration shortcut for the common
<Gallery images={...}/> v13 usage.
No teaching content — just enough to point consumers at the right
primitives. Feature docs own the full usage.
|
🎉 This PR is included in version 14.0.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 Goal
Add
ai-docs/ai-migration.md— a token-optimized, execution-only guide for coding agents performing the v13 → v14 migration. Distills the 62 confirmed breaking changes fromai-docs/breaking-changes.mdinto ordered phases, rename lists, and code-level rewrites.Prune the now-legacy
@stream-io/stream-chat-csswiring. The package is no longer installed (absent frompackage.jsonandyarn.lock;dist/has noscss/,css/v2/, orassets/), but stale tooling and docs around it remained. This PR removes those references so the repo reflects reality.🛠 Implementation details
New
ai-docs/ai-migration.md(~415 lines), organized into 8 ordered phases:.d.tsfiles; never rely on pretraining knowledge)MessageOptions,EditMessageForm,MessageListNotifications,ConnectionStatus, etc.)Channel/ChannelListprops toWithComponentsmessageActionSet,quick-dropdown-toggle,handleDeletesemantics)ChatView, explicit query limitsStyle is optimized for token efficiency: bullet lists instead of markdown tables (no pipe/padding overhead), no commit SHAs, no audit metadata, no motivation prose. Verification section is package-manager agnostic (detects
pnpm/yarn/bun/npmfrom lockfiles).Legacy
@stream-io/stream-chat-csscleanup:ai-docs/DEPRECATED_API_REMOVAL_PLAN.md— superseded by the new guide../dist/scss/*and./scss/*entries frompackage.jsonexports—dist/scss/is no longer emitted.scripts/copy-css.sh— not wired into the build script; unreferenced outside stale docs.scripts/merge-stream-chat-css-docs.sh— copies docs into./docusaurus/docs/React, a directory that no longer exists in this repo.@stream-io/stream-chat-cssentry from.github/dependabot.ymlsince the package isn't installed.CLAUDE.mdto reflect the current 4-step build (build-translations,vite build,tsc,build-styling) and the single-source styling tree undersrc/styling/.🎨 UI Changes
N/A — docs + build tooling only.