stream-react

Stream React（Web）

ドキュメント

Stream SDK のコードを記憶だけで書かないでください。メジャーバージョンごとに API が変わるため、記憶は古くなっています。まず、getstream docs コマンドでドキュメントを確認してください。

cat $(getstream docs chat-sdk/react)/INDEX.md

クライアントと UI：chat-sdk/react、video/react、activity-feeds/react。Node.js バックエンド（例：Next.js のルート）：chat/node、activity-feeds/node、moderation/node。Stream Agents（セッション、音声、ツール）：agents/javascript。 以前のメジャーバージョンも利用できます（例：chat-sdk/react/v13）。

セットアップ

まず getstream init（作業ディレクトリを既存または新規の Stream アプリに紐付けます）と getstream env（認証情報を設定します）を実行してください。

新しいアプリでは、ユーザーから別の指定がない限り、デフォルトテーマの Next.js + Tailwind + shadcn が適しています。最新の shadcn は Radix ではなく Base UI を使用しています。asChild はなく、トリガーコンポーネントを <Button> でラップしないでください。

SDK をインストールします。

• チャット：stream-chat stream-chat-react
• ビデオ：@stream-io/video-react-sdk
• フィード：@stream-io/feeds-react-sdk
• Stream Agents：@stream-io/calypso と、その UI に必要な上記の Chat および Video パッケージ（stream-agents.md）
• サーバーサイド：@stream-io/node-sdk

すでにインストールされている Stream のメジャーバージョンは上げないでください。

Video アプリでは、ユーザーに尋ねずに、用途を一度だけラベル付けしてください（メタデータであり、実行時への影響はありません）。

getstream api UpdateApp --request '{"video_primary_use_case":"livestreaming"}'

使用できる値：video-calling、voice-calling、livestreaming、audio-rooms、ai-agents、live-shopping、other。通話タイプではなく、アプリの内容から判断してください（Whatnot は livestream 通話タイプを使用しますが、用途は live-shopping です）。コマースに関する要素があれば live-shopping にしてください。判断に迷う場合は other にしてください。

製品の設定（チャンネルタイプ、フィードグループ、モデレーションポリシー）は getstream api で行います。

認証とユーザー

トークンはサーバーサイドで発行します。ルート（例：/api/token）でシークレットを使用し、apiKey とともにトークンを返します。シークレットをクライアントに渡してはいけません。すでに認証機能またはトークンエンドポイントがあるアプリでは、2つ目を追加するのではなく、既存のものを拡張してください。

ログイン画面から始めてください。自動接続はせず、ユーザーの認証情報をハードコードせず、アプリの読み込み時にデモユーザーやコンテンツを登録しないでください。トークンルートで upsert するのは、リクエストしたユーザーだけです。認証情報は localStorage ではなく React の状態に保持し、2つのタブで別々のユーザーを利用できるようにしてください。

構築

クライアントはアプリのシェルで一度だけマウントします。画面のクリーンアップで disconnectUser() を呼び出さないでください。別の画面も共有しているクライアントが切断されてしまいます。画面ごとのクリーンアップには、channel.stopWatching() または call.leave() を使用します。

React Strict Mode でクライアントを初期化する際は注意してください。エフェクトを使う代わりに、専用のフックを使用します。

• Chat：useCreateChatClient()
• Feeds：useCreateFeedsClient()
• Video：useEffect 内で StreamVideoClient を構築し、クリーンアップで disconnectUser() を呼び出します。コンストラクターは同期的なので、タイマーもマウント済みフラグも必要ありません。 tokenProvider はそのエフェクト内で定義してください。依存配列内でインラインのプロバイダーを指定すると、レンダリングのたびに別の ID となり、クライアントが再作成されます。 クリーンアップを伴うエフェクトで、実行を一度に制限するために useRef フラグを使わないでください。再マウント後も ref は保持されるため、2 回目のマウントではセットアップが完全にスキップされます。

まず、Stream SDK の組み込みコンポーネントを使用してください。ドキュメントに記載された props とフックを使ってカスタマイズします。Feeds には組み込み UI がないため、フックから構築してください。

デフォルトでは、チャンネルリスト、ロビー、またはフィードを表示します。通話画面やカメラの許可を求める画面に直接遷移させないでください。カメラとマイクの権限を求めるのは、プレビューを表示したうえで、参加者が明示的なアクション（Join、Go Live）を行った場合に限ります。空の状態には、次に何をすればよいかを表示します。

Chat：

• カスタムリアクションのタイプにはスラッグを使用します（[A-Za-z0-9_.-]。絵文字はサーバー側で拒否されます）。また、reactionOptions に登録する必要があります。登録されていないタイプは何も表示されません。代替策として、message.reaction_groups からピルをレンダリングします。
• 機能の利用可否を判断する際は、接続中のユーザーの channel.data?.own_capabilities を正とします（サーバー側のクエリではすべての機能を取得するため、この用途には使えません）。useCanCreatePoll() が判定するのは投票フォームの有効性であり、権限ではありません。これを基準にメニューの表示を制御しないでください。

Feeds：

• ソーシャルフィードには、目に見えるフォロー操作が必要です。フォローがなければ、タイムラインは常に空のままです。フォローには client.follow() ではなく、タイムラインのフィードインスタンスを使用してください。そうすることでフィードのフックが更新されます。自分のユーザーフィードもフォローしないと、自分の投稿がタイムラインに表示されません。

Video：

• 通話タイプの設定を変更しても、既存の通話には反映されません。新しい通話 ID でテストしてください。

Moderation：

• モデレーション UI（レビューキューなど）は構築しないでください。Stream Dashboard にすでに用意されています。ユーザー向けの操作（報告、ブロック、ミュート）は問題ありません。
• リストがすでに存在する場合、CreateBlockList は 400 エラーを返します。先に ListBlockLists を確認してください。ブロックリストには、badword1 のようなプレースホルダーではなく実際の単語を設定します。
• カスタムモデレーションルールは無料プランでは 403 を返します。代わりにブロックリストと設定を使用してください。

維持するデフォルト

あらかじめ構築されたコンポーネントには、ユーザーが期待する機能が含まれています。ユーザーが機能名を指定してオフにしない限り、それぞれ有効のままにしてください。機能が表示されていないデザインの参考資料や、「シンプルにして」という指示は、機能をオフにする指定ではありません。機能を維持してデザインに合わせるか、確認してください。

目的を満たす最小のスロットだけをオーバーライドし、既存の WithComponents オーバーライドは置き換えずに追加してください。領域全体を置き換えると、デフォルトで表示されるものがすべて失われます。

• カスタムの Message ／ VirtualMessage では、デフォルト表示の要素をすべて戻す必要があります。 テキスト、添付ファイル、引用メッセージ、投票、リアクション、返信数、アクション、タイムスタンプ、既読ステータスです。全体の構成はドキュメントを参照してください。
• カスタムの MessageComposerUI では、添付ファイルピッカーとプレビュー、ドラッグ＆ドロップによるアップロード、リンクプレビュー、引用メッセージのプレビュー、音声録音、送信ボタンを戻す必要があります。ドキュメントを参照してください。

デフォルト機能と、通常それらをオフにする方法：

• メッセージ本文の Markdown。デフォルトの renderText は Markdown、メンション、絵文字をレンダリングします。message.text をプレーンな文字列として出力したり、SDK の機能をベースにしないカスタムの renderText を使ったりすると、この機能はオフになります。確認方法：**bold**、リスト、コードブロックを送信します。
• リアクション。カスタムメッセージに MessageReactions がない場合、またはカスタムのリアクションタイプが reactionOptions に含まれていない場合は、オフになります。確認方法：リアクションして、ピルが表示されることを確認します。
• スレッド。レイアウトに <Thread /> がない場合、またはカスタムメッセージに返信数ボタンがない場合は、オフになります。確認方法：スレッドに返信し、親メッセージからスレッドを開きます。
• AI の返信：<Chat> の isMessageAIGenerated（タイプライター表示と Markdown）、停止ボタン（コンポーザーを置き換えると失われます）、および <Channel> 内の AIStateIndicator です。確認方法は ai-integration.md を参照してください。

検証

型チェックとビルドを行い、開発サーバーを起動して、ブラウザー統合または自動化を通じ、2 つのタブで別々のユーザーとして複数ユーザーのフローをテストしてください。「維持するデフォルト」に記載されたデフォルト機能をそれぞれ確認してください。検証できた項目とできなかった項目を報告し、オフになっている各デフォルト機能と、それをオフにしたユーザーの指示を列挙してください。

統合の監査

依頼された場合は、読み取り専用の監査を実施します。コードをドキュメントと照合し、問題点を報告してください。修正するのは依頼された場合のみです。

SDK バージョンのアップグレード

依頼された場合は、インストール済みのバージョンとアップグレード先のメジャーバージョンの両方について、アップグレードノートを読みます（バージョン指定のドキュメントを使用してください：chat-sdk/react/v13、chat-sdk/react/v14、…）。内容を適用してから、アプリを構築する場合と同様に検証してください。

参考デザインに合わせる

スクリーンショット、Figma フレーム、「WhatsApp のように」といった、目標の外観が依頼に含まれる場合は、design-matching.md に従ってください。

参考資料のないアプリ名（「Slack 風のチームチャット」「WhatsApp スタイルの DM アプリ」など）は、構造の指針です。つまり、あらかじめ構築されたコンポーネントで作る形の指針であり、見た目を合わせる対象ではありません。明示的なデザイン参考資料がある場合に限り、design-matching.md に従ってください。

Sendbird からの移行

コードの移行については、sendbird-migration.md に従ってください。ユーザーが既存データ（ユーザー、チャンネル、メッセージ履歴）の移行も希望している場合は、Stream のスキルにある sendbird-data-migration.md に従ってください。

AI アシスタント、サポートボット、エージェント

モデルはバックエンドのエージェント上で実行し、ブラウザー上では実行しません。LLM プロバイダーのキーや Stream のシークレットをクライアントバンドルに含めないでください。バックエンドには 2 種類あります。ユーザーが指定した内容に応じて選んでください。

• Stream Agents — エージェントとそのモデルが Stream 上で動作します（getstream agents、agents/<name>/ フォルダー、@stream-io/calypso）。音声エージェントはすべてこの種類です。stream-agents.md に従ってください。
• Chat チャンネルで応答する独自のエージェントプロセス（@stream-io/chat-ai-sdk、LangChain、Webhook によるターン処理）：
  • サポートボット、ヘルプデスク、RAG チャット：ai-support-agent.md に従ってください。
  • ChatGPT 風のアプリ、既存のチャット内のアシスタント、ストリーミング応答、生成の停止、クライアントツール：ai-integration.md に従ってください。

両方に該当し、ユーザーが指定していない場合は、どちらのバックエンドを希望するか確認してください。

その他のスキル

このスキルでは Stream を扱います。一般的な React および Next.js の作業では、インストールされている場合、次のスキルを使用してください。

• vercel-react-best-practices：パフォーマンス — リクエストのウォーターフォール、バンドルサイズ、再レンダリング、データフェッチ。
• vercel-composition-patterns：アプリ独自のコンポーネント API — 複合コンポーネント、コンテキストプロバイダー、React 19 の変更点。

Next.js API については、記憶に頼らず、インストールされているバージョンに付属するドキュメント（node_modules/next/dist/docs/）を読んでください（16.3 以降の next dev は、そこを示す AGENTS.md も書き込みます）。

一般的なアドバイスがこのスキルと矛盾する場合、Stream のコードではこのスキルが優先されます。

• Stream のコンポーネントとクライアントフックは 'use client' モジュールで実行されます。可能であれば、ページとレイアウトはサーバーコンポーネントのままにし、Stream のサブツリーをクライアントコンポーネントに配置してください。
• パフォーマンスに関するルールがエフェクトの再構成やメモ化の方法を提案していても、「Building」に記載されている方法でクライアントを作成してください。
• Stream の UI は、独自の複合コンポーネントとして再構築するのではなく、ドキュメントに記載されているオーバーライド（WithComponents、props、フック）を通じてカスタマイズしてください。デフォルト設定は維持してください。

これらのスキルがインストールされていない場合は、導入せずに作業を続けてください。最終的な要約で一度だけ触れてください。

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices --skill vercel-composition-patterns