Skip to content

fix(docs): clarify SSR remote fallback behavior #7

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

Merged
Nsttt merged 1 commit into from
Oct 13, 2026
Merged

fix(docs): clarify SSR remote fallback behavior #7

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
5 changes: 3 additions & 2 deletions apps/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,9 @@ server show "Rendered on the server" until they hydrate.
`@module-federation/vite` and `vite`.

Stop a remote while the hosts are open and reload them: each host keeps
rendering and shows its fallback, then renders the remote again once it is
back. The same holds for a host started before its remotes.
rendering, the client-side boundary shows its fallback, and the remote renders
again once it is back. An SSR error boundary fallback is not guaranteed in the
initial server HTML. The same holds for a host started before its remotes.

## Notes

Expand Down
16 changes: 10 additions & 6 deletions packages/tanstack/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,7 @@ const StatusCard = lazyRemote(() => import("remote/StatusCard"));

export const Route = createFileRoute("/")({
// Loading the remote before rendering puts its markup in the server response.
// A failed load must not fail the route: the boundary renders a fallback.
// Catch route-loader failures so an unavailable remote does not fail the route.
loader: async () => {
const [stylesheets] = await Promise.all([
getRemoteStylesheets("https://remote.test/mf-manifest.json", "./StatusCard").catch(() => []),
Expand All @@ -238,13 +238,17 @@ export const Route = createFileRoute("/")({
```

`RemoteBoundary` stands for any error boundary around a `Suspense`; the
examples in `apps/` include one.
examples in `apps/` include one. The route loader must catch remote failures.
During SSR, React does not guarantee that an error boundary switches to its
fallback for a rejected lazy module; the fallback is handled during client
rendering or hydration recovery instead.

- **`lazyRemote(load, { retryAfterMs })`** is `React.lazy` for remotes. A
`React.lazy` component that fails once stays failed, so a server that hit a
remote outage would render the fallback until it restarts. `lazyRemote` loads
again on the first render after `retryAfterMs` (5 seconds by default). The
import itself loads again after a failure too: `@module-federation/vite`
`React.lazy` component that fails once stays rejected until its lazy instance
is recreated. `lazyRemote` recreates it on the first render after
`retryAfterMs` (5 seconds by default), so a later request can retry a remote
that recovered. This retry policy does not make an SSR error boundary render
its fallback. The import itself loads again after a failure too: `@module-federation/vite`
1.23.3+ retries failed server loads, and the Rsbuild adapter removes a failed
remote module from Rspack's module cache.
- **`getRemoteStylesheets(manifestUrl, expose, { maxAgeMs })`** lists the
Expand Down
Loading