Skip to content

docs(bridge): clarify createLazyComponent error handling #4945

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dmchoi77 wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −9
Open

docs(bridge): clarify createLazyComponent error handling #4945

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions apps/website-new/docs/en/guide/bridge/react/load-component.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

This chapter introduces how to use `createLazyComponent` to load remote React components on demand in a host application.

`createLazyComponent` is a higher-level loading API for React component scenarios. Compared with directly loading a module and wiring up `React.lazy`, `Suspense`, and error boundaries yourself, it builds those pieces into the API and additionally provides:
`createLazyComponent` is a higher-level loading API for React component scenarios. Compared with directly loading a module and wiring up `React.lazy` and `Suspense` yourself, it builds those pieces into the API and additionally provides:

- **Declarative loading and fallback**: no need to manually wrap `React.Suspense` and error boundaries
- **Declarative loading and failure fallback**: handles the loading state with `React.Suspense` and provides fallback UI for remote module loading or data-fetch failures
- **Data prefetching**: use `prefetch` to start dependency requests before the component loads, avoiding request waterfalls where data is requested only after the component is ready
- **SSR control**: precisely control whether remote components render on the server, helping avoid CSS flickering issues

Expand Down Expand Up @@ -181,7 +181,9 @@ Sets the delay time for displaying loading state in milliseconds. If the loading
- Required: Yes
- Default: `undefined`

The error component rendered when component **loading** or **rendering** fails.
The error component rendered when remote module loading or data fetching fails.

It does not catch errors thrown while React renders the loaded component or its descendants. To handle client-side render errors, wrap the lazy component in an Error Boundary in the host application. Server-rendering errors must be handled by the server rendering pipeline because React Error Boundaries do not catch them.
Comment on lines +184 to +186

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include lazy-resolution failures in Error Boundary guidance

When the configured export is missing or is not a function—or when the loader's second invocation rejects—the error is thrown from the React.lazy factory (packages/bridge/bridge-react/src/lazy/createLazyComponent.tsx:286-338), outside the fallback handling around getData. Thus fallback does not cover every remote-module loading/resolution failure as stated here, while the following guidance only mentions errors thrown by the loaded component or its descendants. Document that these lazy-resolution errors also require a host Error Boundary so users do not rely on fallback for a misconfigured export or second-load failure.

Useful? React with 👍 / 👎.


#### export

Expand Down
8 changes: 5 additions & 3 deletions apps/website-new/docs/pt-BR/guide/bridge/react/load-component.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

Este chapter introduces como para usar `createLazyComponent` para carregar remote React componentes on demand em uma aplicação host.

`createLazyComponent` é uma higher-level carregamento API for React componente scenarios. Compared com diretamente carregamento um módulo e wiring up `React.lazy`, `Suspense`, e erro boundaries yourself, it builds those pieces no API e additionally fornece:
`createLazyComponent` é uma API de carregamento de alto nível para cenários com componentes React. Em comparação com carregar um módulo diretamente e configurar `React.lazy` e `Suspense` manualmente, ela incorpora esses recursos à API e também oferece:

- **Declarative carregamento e fallback**: no precisa manually wrap `React.Suspense` e erro boundaries
- **Carregamento declarativo e fallback de erro**: gerencia o estado de carregamento com `React.Suspense` e fornece um fallback para falhas ao carregar o módulo remoto ou buscar dados
- **Dados prefetching**: use `prefetch` para começa dependência requests antes o componente carrega, avoiding request waterfalls onde dados é requested apenas depois o componente é ready
- **SSR control**: precisely control whether remote componentes render no servidor, helping avoid CSS flickering issues

Expand Down Expand Up @@ -181,7 +181,9 @@ Sets o delay time for displaying estado de carregamento em milliseconds. Se o ca
- Obrigatório: Yes
- Padrão: `undefined`

O erro componente rendered quando componente **carregamento** ou **renderização** fails.
O componente de erro renderizado quando o carregamento do módulo remoto ou a busca de dados falha.

Ele não captura erros lançados durante a renderização React do componente carregado ou de seus descendentes. Para tratar erros de renderização no cliente, envolva o componente lazy em um Error Boundary no aplicativo host. Erros de renderização no servidor devem ser tratados pelo pipeline de renderização do servidor, pois Error Boundaries do React não os capturam.

#### exporte

Expand Down
8 changes: 5 additions & 3 deletions apps/website-new/docs/zh/guide/bridge/react/load-component.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

本章介绍如何使用 `createLazyComponent` 在宿主应用中按需加载远程 React 组件。

`createLazyComponent` 是面向 React 组件场景的高阶加载方式。相比直接使用模块后再自己接 `React.lazy` / `Suspense` / 错误边界，它把这些工作内置在 API 中，并额外提供：
`createLazyComponent` 是面向 React 组件场景的高阶加载方式。相比直接加载模块后再自行接入 `React.lazy` 与 `Suspense`，它把这些能力内置在 API 中，并额外提供：

- **声明式 loading 与 fallback**：无需手动包 `React.Suspense` 与错误边界
- **声明式 loading 与失败 fallback**：通过 `React.Suspense` 处理 loading 状态，并为远程模块加载或数据获取失败提供 fallback
- **数据预取**：配合 `prefetch` 在组件加载前发起依赖请求，避免组件就绪后才串行请求数据带来的瀑布
- **SSR 控制**：可精细控制远程组件是否在服务端渲染，避免出现 CSS 闪烁问题

Expand Down Expand Up @@ -182,7 +182,9 @@ export default App;
- 是否必填：是
- 默认值：`undefined`

当组件**加载**或**渲染**失败时，所渲染的容错组件。
远程模块加载或数据获取失败时所渲染的容错组件。

它不会捕获已加载组件或其后代在 React 渲染期间抛出的错误。若要处理客户端渲染错误，请在宿主应用中使用 Error Boundary 包裹该懒加载组件。服务端渲染错误需要由服务端渲染流程处理，因为 React Error Boundary 无法捕获这类错误。

#### export

Expand Down
Loading