liveblocks-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Liveblocks best practices

Liveblocks最佳实践

When to use this skill

使用此技能的场景

Use this skill when implementing features using any Liveblocks packages, for example

@liveblocks/react

@liveblocks/node

. This could be related to features like realtime multiplayer, commenting, notifications, cursors, avatar stacks, AI, and more. This also includes technologies like Liveblocks Storage, Yjs, Tiptap, BlockNote, Lexical, React Flow, tldraw, and more.

当你使用任何Liveblocks包实现功能时，均可使用此技能，例如

@liveblocks/react

或

@liveblocks/node

。这可能涉及实时多人协作、评论、通知、光标、头像堆叠、AI等功能，也涵盖Liveblocks Storage、Yjs、Tiptap、BlockNote、Lexical、React Flow、tldraw等技术。

Quick reference

快速参考

A number of reference files are available in the

references/

directory. You must read the list below, and load relevant files as needed. For example,

add-user-information

is available in the

references/add-user-information.md

file.

references/

目录下提供了多个参考文件。你必须阅读以下列表，并根据需要加载相关文件。例如，

add-user-information

对应的文件是

references/add-user-information.md

。

References

参考内容

```
add-user-information
```
: Add user information to your application, such as name, avatar, color, and more. Users will no longer be anonymous. Useful for displaying user info in comments, comments mention suggestions, notifications, cursors, avatar stacks.
```
ai-as-a-collaborator
```
: Use agentic workflows to allow AI to collaborate like a human inside your Liveblocks application.
```
ai-chats-with-tools-knowledge-components
```
: Set up and troubleshoot chats with RAG, knowledge, custom components, tool calling, custom models. Different to AI as a collaborator, as it is NOT workflow based.
```
auth-endpoint-callback
```
: Use a callback function to authenticate users, instead of passing a string to
```
authEndpoint
```
. Useful for passing custom headers to your back end, and for preventing automatic reconnection when the token is invalid.
```
authenticating-with-access-tokens
```
: Alternative method for authenticating users with their ID and info, best for very simple permissions.
```
authenticating-with-id-tokens
```
: Recommended method for authenticating users with their ID and info, best for complex permissions.
```
avoid-hitting-user-limit-in-rooms
```
: How to avoid rooms filling up with users.
```
compartmentalize-resources-with-organizations
```
: Use organizations to create workspaces/tenants and compartmentalize resources, such as rooms, notifications, comment threads, and more. You can filter by organization when listing rooms and more.
```
create-custom-comment-composer
```
: Build your own commenting composer (advanced use cases only).
```
create-custom-realtime-multiplayer
```
: Use Liveblocks Storage to build fully custom conflict-resolved multiplayer apps, like Figma, Pitch, Spline. Helpful for one-off realtime features too, like simple properties in a document.
```
create-custom-text-editor-toolbar
```
: Set up a styled toolbar, static or floating next to your selection, in Tiptap and Lexical.
```
create-rooms-manually
```
: Always create rooms yourself in production applications, setting permissions, organization, metadata.
```
customize-thread-components
```
: Use slots to customize comments inside of threads, and their different parts.
```
dark-mode-styles
```
: You can import CSS styling for dark mode themes.
```
develop-and-test-locally
```
: Set up a local dev server, and use it for Continuous Integration (CI) and End-to-End (E2E) testing. Connect to your app not online.
```
devtools-extension
```
: Inspect Liveblocks Storage, Yjs, presence, events, and connected users with DevTools extensions for Chrome, Firefox, Edge.
```
edit-component-text-strings
```
: Override strings in default components, such as button values, tooltip text, error text, more. Also helpful for setting other languages.
```
exhaustive-deps-with-usemutation
```
: Prevent and fix stale-closure bugs with
```
useMutation
```
by configuring the
```
react-hooks/exhaustive-deps
```
ESLint rule.
```
handling-connection-errors
```
: Handle problems joining rooms because of permissions, authentication, changed room IDs.
```
handling-full-rooms
```
: Handle problems caused by joining full rooms.
```
handling-hook-and-component-errors
```
: Handle errors caused by hooks and pre-built components.
```
handling-unstable-connections
```
: Implement fallbacks and error messages when users have poor network conditions.
```
log-out-of-liveblocks
```
: Rarely useful, but helpful in specific SPA situations where you cannot navigate the page to log out.
```
multiplayer-react-flow
```
: Use the Liveblocks React Flow package to create multiplayer diagrams with cursors and more.
```
multiple-text-editors
```
: Add multiple Tiptap or BlockNote editors to the same page. Optionally use Storage to hold their field IDs.
```
offline-support-in-text-editors
```
: Give your text editors the illusion of a quicker load time.
```
override-css-variables
```
: Add custom styles to the default components by overriding Liveblocks CSS variables.
```
performant-others-and-presence
```
: Prevent unnecessary presence renders by using
```
useOtherConnectionIds
```
,
```
useOthersMapped
```
,
```
useOther
```
, and
```
shallow
```
to update components only when necessary.
```
performant-storage-with-selectors
```
: Prevent unnecessary storage renders by using
```
useStorage
```
selectors and
```
shallow
```
.
```
prevent-unsaved-changes-being-lost
```
: Stop losing unsynched or unsaved changes.
```
primitive-component-parts
```
: Use primitives to create custom components or to merge components from your design system into Liveblocks UI.
```
remove-liveblocks-branding
```
: A Liveblocks logo badge appears in the bottom right of the screen, this is how to remove it.
```
rendering-error-components
```
: Use
```
ErrorBoundary
```
to structure your app with error fallbacks.
```
rendering-loading-components
```
: Use
```
ClientSideSuspense
```
to performantly structure your app with loading skeletons and spinners.
```
send-comment-notification-emails
```
: Send email notifications to users when they have unread comments. These comments are sent via webhooks, and are triggered when a user is mentioned, or has participated in a thread.
```
smoother-realtime-updates
```
: Make presence and storage run at a higher frame rate, appearing more smooth. Using this option, updates can be received more frequently.
```
suspense-vs-regular-hooks
```
: You must read this when using any Liveblocks hooks. React suspense uses
```
ErrorBoundary
```
and
```
ClientSideSuspense
```
components. Regular hooks use
```
{ error, isLoading }
```
values.
```
tiptap-best-practices
```
: Server-side rendering, starter kit extensions, initial content, unsaved changes, more.
```
trigger-custom-notifications
```
: Trigger any kind of notification in your inbox, even those unrelated to commenting.
```
type-liveblocks-correctly
```
: Always use TypeScript to type Liveblocks where available. Presence, others, user info, storage, metadata, room info, notifications activities, can all be automatically typed.
```
url-params-in-room-id
```
: Use URL params in room IDs to create rooms, and incorporate document titles in the URL.
```
utility-components
```
: Import a ready-made emoji picker, or human-readable timestamps, durations, file sizes.
```
yjs-best-practices
```
: YKeyValue, subdocuments, V2 encoding, double imports, getYjsProviderForRoom. NOT relevant if you're using Tiptap, BlockNote, or Lexical.
```
z-index-issues
```
: Fix z-index problems by targeting portaled elements.

```
add-user-information
```
: 为你的应用添加用户信息，如姓名、头像、颜色等。用户将不再以匿名身份显示。适用于在评论、评论提及建议、通知、光标、头像堆叠中展示用户信息。
```
ai-as-a-collaborator
```
: 使用智能代理工作流，让AI能够像人类一样在你的Liveblocks应用内协同工作。
```
ai-chats-with-tools-knowledge-components
```
: 设置并调试带有RAG、知识库、自定义组件、工具调用、自定义模型的聊天功能。与AI协作者不同，此功能不基于工作流。
```
auth-endpoint-callback
```
: 使用回调函数对用户进行身份验证，而非将字符串传递给
```
authEndpoint
```
。适用于向后端传递自定义标头，以及在令牌无效时阻止自动重新连接。
```
authenticating-with-access-tokens
```
: 使用访问令牌对用户及其信息进行身份验证的替代方法，非常适合简单权限场景。
```
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
```
，避免不必要的存储渲染。
```
prevent-unsaved-changes-being-lost
```
: 防止未同步或未保存的更改丢失。
```
primitive-component-parts
```
: 使用基础组件创建自定义组件，或将你的设计系统组件与Liveblocks UI合并。
```
remove-liveblocks-branding
```
: Liveblocks的Logo徽章会显示在屏幕右下角，此内容介绍如何移除它。
```
rendering-error-components
```
: 使用
```
ErrorBoundary
```
为应用设置错误降级方案。
```
rendering-loading-components
```
: 使用
```
ClientSideSuspense
```
为应用设置加载骨架屏和加载动画，提升性能。
```
send-comment-notification-emails
```
: 当用户有未读评论时，向其发送邮件通知。这些评论通过Webhook发送，在用户被提及或参与线程时触发。
```
smoother-realtime-updates
```
: 提高在线状态和存储的帧率，让更新看起来更流畅。使用此选项可以更频繁地接收更新。
```
suspense-vs-regular-hooks
```
: 使用任何Liveblocks钩子时，你必须阅读此内容。React Suspense使用
```
ErrorBoundary
```
和
```
ClientSideSuspense
```
组件。常规钩子使用
```
{ error, isLoading }
```
值。
```
tiptap-best-practices
```
: 服务端渲染、入门套件扩展、初始内容、未保存更改等最佳实践。
```
trigger-custom-notifications
```
: 在收件箱中触发任何类型的通知，即使与评论无关。
```
type-liveblocks-correctly
```
: 尽可能使用TypeScript为Liveblocks添加类型定义。在线状态、其他用户信息、存储、元数据、房间信息、通知活动等均可自动添加类型。
```
url-params-in-room-id
```
: 在房间ID中使用URL参数创建房间，并在URL中加入文档标题。
```
utility-components
```
: 导入现成的表情选择器，或人类可读的时间戳、时长、文件大小组件。
```
yjs-best-practices
```
: YKeyValue、子文档、V2编码、重复导入、getYjsProviderForRoom。如果你使用Tiptap、BlockNote或Lexical，则此内容不相关。
```
z-index-issues
```
: 通过定位门户元素修复z-index问题。

Note

注意事项

Some files link to markdown files in the Liveblocks docs, for example:

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

When linking users to these pages, remove

.md

from the link, so they can view the full content:

https://liveblocks.io/docs/concepts

部分文件链接到Liveblocks文档中的markdown文件，例如：

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

当引导用户访问这些页面时，请移除链接中的

.md

，以便他们查看完整内容：

https://liveblocks.io/docs/concepts

Liveblocks packages

Liveblocks包

Always check if we provide a package for your technology. For example, if you're using React Flow, you should use @liveblocks/react-flow
.

@liveblocks/client
: JavaScript client. Can use with any framework, e.g. Vue, Svelte, vanilla JS.
@liveblocks/react
: React client. Contains hooks and components..
@liveblocks/react-ui
: Pre-built React UI components and primitives.
```
@liveblocks/react
```
for data and hooks.
@liveblocks/react-tiptap
: Collaborative Tiptap integration for React.
@liveblocks/react-blocknote
: Collaborative BlockNote integration for React.
@liveblocks/react-lexical
: Collaborative Lexical integration for React.
@liveblocks/node-lexical
: Server-side Lexical utilities for Node.js.
@liveblocks/node-prosemirror
: Server-side ProseMirror utilities For Node.js. Also works with Tiptap and BlockNote.
@liveblocks/react-flow
: Multiplayer React Flow.
@liveblocks/yjs
: Yjs provider backed by Liveblocks rooms.
@liveblocks/redux
: Sync Liveblocks room state with a Redux store.
@liveblocks/zustand
: Sync Liveblocks room state with Zustand.
@liveblocks/node
: Node.js server SDK. Use for auth and lots more.
@liveblocks/emails
: Build notification emails more easily.
@liveblocks/chat-sdk-adapter
: Make multi-platform (Liveblocks, Slack, Discord, etc.) chat bots.
Python SDK: Python server SDK. Use for auth and lots more.
REST API: HTTP API. Use for auth and lots more.

请始终检查我们是否为你的技术提供了对应包。例如，如果你使用React Flow，应该使用**

@liveblocks/react-flow

**。

@liveblocks/client
: JavaScript客户端。可用于任何框架，如Vue、Svelte、原生JS。
@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。用于身份验证等多种场景。

If a technology is not listed here

如果此处未列出你的技术

If the users want to set up a new technology, first check the following resources to see if a package exists:

如果用户想要集成一种新的技术，请先查看以下资源确认是否存在对应包：

Learn more

了解更多

Learn more in Liveblocks docs.

在Liveblocks文档中了解更多内容。