liveblocks-best-practices

Liveblocks のベストプラクティス

このスキルを使用する場面

@liveblocks/react や @liveblocks/node など、Liveblocks のパッケージを使って機能を実装する際に、このスキルを使用してください。 リアルタイムでのマルチプレイヤー機能、コメント、通知、カーソル、アバターのスタック、AI などの機能が対象です。また、Liveblocks Storage、Yjs、Tiptap、BlockNote、Lexical、React Flow、tldraw などのテクノロジーも含まれます。

クイックリファレンス

references/ ディレクトリには、複数のリファレンスファイルがあります。以下の一覧を確認し、必要に応じて関連ファイルを読み込んでください。たとえば、add-user-information は references/add-user-information.md ファイルにあります。

リファレンス

• add-user-information: 名前、アバター、色などのユーザー情報をアプリケーションに追加します。ユーザーが匿名でなくなります。コメント内でのユーザー情報の表示、コメントでのメンション候補、通知、カーソル、アバターのスタックに便利です。
• ai-as-a-collaborator: エージェント型ワークフローを利用して、Liveblocks アプリケーション内で AI が人間のように共同作業できるようにします。
• ai-chats-with-tools-knowledge-components: RAG、ナレッジ、カスタムコンポーネント、ツール呼び出し、カスタムモデルを使ったチャットを設定し、トラブルシューティングします。ワークフローをベースとしないため、AI をコラボレーターとして使う場合とは異なります。
• auth-endpoint-callback: authEndpoint に文字列を渡す代わりに、コールバック関数を使ってユーザーを認証します。バックエンドにカスタムヘッダーを渡す場合や、トークンが無効なときに自動再接続を防ぐ場合に便利です。
• authenticating-with-access-tokens: ユーザーを ID と情報で認証する別の方法です。非常にシンプルな権限設定に最適です。
• authenticating-with-id-tokens: ユーザーを ID と情報で認証する推奨方法です。複雑な権限設定に最適です。
• avoid-hitting-user-limit-in-rooms: ルームがユーザーでいっぱいになるのを防ぐ方法です。
• compartmentalize-resources-with-organizations: 組織を使ってワークスペース／テナントを作成し、ルーム、通知、コメントスレッドなどのリソースを分離します。ルームの一覧表示などでは、組織で絞り込むことができます。
• create-custom-comment-composer: 独自のコメント入力欄を作成します（高度なユースケースのみ）。
• create-custom-realtime-multiplayer: Liveblocks Storage を使って、Figma、Pitch、Spline のような、競合解決に対応した完全カスタムのマルチプレイヤーアプリを作成します。ドキュメント内のシンプルなプロパティのような、単発のリアルタイム機能にも便利です。
• create-custom-text-editor-toolbar: Tiptap と Lexical で、スタイルを設定したツールバーを選択範囲の横に固定またはフローティングで表示するよう設定します。
• create-rooms-manually: 本番アプリケーションでは、権限、組織、メタデータを設定し、必ず自分でルームを作成します。
• customize-thread-components: スロットを使って、スレッド内のコメントとその各部分をカスタマイズします。
• dark-mode-styles: ダークモードのテーマ用の CSS スタイルをインポートできます。
• develop-and-test-locally: ローカル開発サーバーを設定し、継続的インテグレーション（CI）やエンドツーエンド（E2E）テストに使用します。オンラインでなくても、アプリに接続できます。
• devtools-extension: Chrome、Firefox、Edge 用の DevTools 拡張機能で、Liveblocks Storage、Yjs、プレゼンス、イベント、接続中のユーザーを調べます。
• edit-component-text-strings: ボタンの値、ツールチップのテキスト、エラーのテキストなど、デフォルトコンポーネントの文字列を上書きします。他の言語を設定する場合にも便利です。
• exhaustive-deps-with-usemutation: react-hooks/exhaustive-deps ESLint ルールを設定して、useMutation による古いクロージャのバグを防ぎ、修正します。
• handling-connection-errors: 権限、認証、ルーム ID の変更が原因でルームに参加できない問題に対処します。
• handling-full-rooms: 満員のルームへの参加が原因で発生する問題に対処します。
• handling-hook-and-component-errors: フックや事前構築済みコンポーネントが原因で発生するエラーに対処します。
• handling-unstable-connections: ユーザーのネットワーク状態が悪い場合のフォールバックとエラーメッセージを実装します。
• log-out-of-liveblocks: 使用する機会はまれですが、ログアウトするためにページを遷移できない特定の SPA の状況で役立ちます。
• multiplayer-react-flow: Liveblocks React Flow パッケージを使って、カーソルなどを備えたマルチプレイヤー図を作成します。
• multiple-text-editors: 同じページに複数の Tiptap または BlockNote エディターを追加します。必要に応じて、Storage を使ってフィールド ID を保持できます。
• offline-support-in-text-editors: テキストエディターの読み込みが速くなったように見せます。
• override-css-variables: Liveblocks の CSS 変数を上書きして、デフォルトコンポーネントにカスタムスタイルを追加します。
• performant-others-and-presence: useOtherConnectionIds、useOthersMapped、useOther、shallow を使い、必要な場合にのみコンポーネントを更新して、不要なプレゼンスの再レンダリングを防ぎます。
• performant-storage-with-selectors: useStorage セレクターと shallow を使って、不要な Storage の再レンダリングを防ぎます。
• prevent-unsaved-changes-being-lost: 同期されていない変更や保存されていない変更が失われないようにします。
• primitive-component-parts: プリミティブを使ってカスタムコンポーネントを作成するか、デザインシステムのコンポーネントを Liveblocks UI に統合します。
• remove-liveblocks-branding: 画面の右下に表示される Liveblocks のロゴバッジを削除する方法です。
• rendering-error-components: ErrorBoundary を使って、エラー時のフォールバックを備えたアプリの構成にします。
• rendering-loading-components: ClientSideSuspense を使って、ローディングスケルトンやスピナーを備えたアプリの構成を効率化します。
• send-comment-notification-emails: 未読コメントがあるユーザーにメール通知を送信します。これらのコメントはウェブフック経由で送信され、ユーザーがメンションされたとき、またはスレッドに参加したときにトリガーされます。
• smoother-realtime-updates: プレゼンスと Storage のフレームレートを上げて、より滑らかに表示します。このオプションを使うと、更新をより頻繁に受信できます。
• suspense-vs-regular-hooks: Liveblocks のフックを使う場合は必ず読んでください。React suspense は ErrorBoundary と ClientSideSuspense コンポーネントを使います。通常のフックは { error, isLoading } の値を使います。
• tiptap-best-practices: サーバーサイドレンダリング、スターターキットの拡張機能、初期コンテンツ、保存されていない変更などについて説明します。
• trigger-custom-notifications: コメントとは関係のないものも含め、受信トレイであらゆる種類の通知をトリガーします。
• type-liveblocks-correctly: 対応している場合は、必ず TypeScript を使って Liveblocks に型を付けます。プレゼンス、他のユーザー、ユーザー情報、Storage、メタデータ、ルーム情報、通知アクティビティには、すべて自動的に型を付けることができます。
• url-params-in-room-id: URL パラメーターをルーム ID に使ってルームを作成し、ドキュメントのタイトルを URL に含めます。
• utility-components: すぐに使える絵文字ピッカーや、人が読みやすいタイムスタンプ、時間、ファイルサイズをインポートします。
• yjs-best-practices: YKeyValue、サブドキュメント、V2 エンコーディング、二重インポート、getYjsProviderForRoom について説明します。Tiptap、BlockNote、Lexical を使用している場合は関係ありません。
• z-index-issues: ポータル要素を対象にして z-index の問題を修正します。

注記

一部のファイルは、Liveblocks ドキュメント内の Markdown ファイルにリンクしています。たとえば、次のとおりです。

https://liveblocks.io/docs/concepts.md

これらのページにユーザーを案内する場合は、リンクから .md を削除してください。そうすると、ページの内容全体を表示できます。

https://liveblocks.io/docs/concepts

Liveblocks パッケージ

ご利用のテクノロジー向けのパッケージが提供されているか、必ず確認してください。たとえば、React Flow を使用している場合は、@liveblocks/react-flow を使用してください。

• @liveblocks/client：JavaScript クライアント。Vue、Svelte、バニラ JavaScript など、あらゆるフレームワークで使用できます。
• @liveblocks/react：React クライアント。フックとコンポーネントが含まれています。
• @liveblocks/react-ui：すぐに使える React UI コンポーネントとプリミティブ。データとフックには @liveblocks/react を使用します。
• @liveblocks/react-tiptap：React 用の共同編集 Tiptap 統合。
• @liveblocks/react-blocknote：React 用の共同編集 BlockNote 統合。
• @liveblocks/react-lexical：React 用の共同編集 Lexical 統合。
• @liveblocks/node-lexical：Node.js 用のサーバーサイド Lexical ユーティリティ。
• @liveblocks/node-prosemirror：Node.js 用のサーバーサイド ProseMirror ユーティリティ。Tiptap と BlockNote にも対応しています。
• @liveblocks/react-flow：マルチプレイヤー React Flow。
• @liveblocks/yjs：Liveblocks ルームを基盤とする Yjs プロバイダー。
• @liveblocks/redux：Liveblocks ルームの状態を Redux ストアと同期します。
• @liveblocks/zustand：Liveblocks ルームの状態を Zustand と同期します。
• @liveblocks/node：Node.js サーバー SDK。認証などに使用します。
• @liveblocks/emails：通知メールをより簡単に作成できます。
• @liveblocks/chat-sdk-adapter：マルチプラットフォーム（Liveblocks、Slack、Discord など）のチャットボットを作成できます。
• Python SDK：Python サーバー SDK。認証などに使用します。
• REST API：HTTP API。認証などに使用します。

テクノロジーがここに記載されていない場合

ユーザーが新しいテクノロジーのセットアップを希望する場合は、まず次のリソースを確認し、パッケージが存在するか調べてください。

• llms.txt
• ドキュメント
• サンプル

詳細はこちら

Liveblocks ドキュメントで詳細を確認してください。