Skip to content

fix(dynamic): respect parent Suspense boundaries when no loading component is provided#93882

Open
MD-Mushfiqur123 wants to merge 2 commits into
vercel:canaryfrom
MD-Mushfiqur123:fix/dynamic-suspense-hierarchy
Open

fix(dynamic): respect parent Suspense boundaries when no loading component is provided#93882
MD-Mushfiqur123 wants to merge 2 commits into
vercel:canaryfrom
MD-Mushfiqur123:fix/dynamic-suspense-hierarchy

Conversation

@MD-Mushfiqur123
Copy link
Copy Markdown

What?

Fixes next/dynamic() creating an unnecessary inner <Suspense> boundary with an empty fallback when no loading component is provided, which prevents parent <Suspense> boundaries from working and causes layout flicker.

Why?

When using next/dynamic() without a loading component inside a parent <Suspense>:

<Suspense fallback={<FullPageSkeleton />}>
  <DynamicComponent /> {/* no loading prop */}
</Suspense>

The current code forces an inner <Suspense> boundary when ssr: false (line 52: const hasSuspenseBoundary = !opts.ssr || !!opts.loading). This inner boundary has fallback={null}, which:

  1. Catches the lazy suspension before it reaches the parent <Suspense>
  2. Renders nothing during loading, causing a visible layout flicker
  3. Makes the parent fallback completely useless

How?

lazy-dynamic/loadable.tsx: Changed the condition so that a <Suspense> boundary is only created when a loading component is explicitly provided. When loading is null (default), use <Fragment> instead, allowing any parent <Suspense> to properly handle the loading state.

loadable.shared-runtime.tsx: Added a null guard for opts.loading to prevent a React.createElement(null, ...) crash when no loading component is provided.

Verification

  • When loading=<Component>: <Suspense> is used with the given fallback (unchanged behavior)
  • When loading=null (default) with ssr=true: <Fragment> is used, parent <Suspense> catches the lazy state
  • When loading=null (default) with ssr=false: <Fragment> is used, <BailoutToCSR> triggers the parent <Suspense>

Fixes #73830

Comment on lines +51 to +54
// Only wrap in a Suspense boundary when a loading component is explicitly provided.
// When no loading component is given, use Fragment to allow parent Suspense
// boundaries to handle the loading state properly.
const hasSuspenseBoundary = !!opts.loading
Copy link
Copy Markdown
Contributor

@vercel vercel Bot May 16, 2026

Choose a reason for hiding this comment

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

When ssr: false and no loading component is provided to next/dynamic(), the Suspense boundary is removed, causing BailoutToCSRError to propagate as a fatal SSR error instead of gracefully bailing out to client-side rendering.

Fix on Vercel

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

dynamic() ignores <Suspense> hierarchy resulting in layout flicker

1 participant