ClerkProvider breaks NextJS SSR w/ Suspense

[cirex-web]

Preliminary Checks

• I have reviewed the documentation: https://clerk.com/docs
• I have searched for existing issues: https://github.com/clerk/javascript/issues
• I have not already reached out to Clerk support via email or Discord (if you have, no need to open an issue here)
• This issue is not a question, general help request, or anything other than a bug report directly related to Clerk. Please ask questions in our Discord community: https://clerk.com/discord.

Reproduction

https://github.com/cirex-web/next-theme-ignored-suspense/tree/clerk

Just a simple next js app with a layout, page, and client component wrapped in a suspense boundary. A promise is thrown in the client component to trigger the suspense boundary.

Publishable key

pk_test_YmVsb3ZlZC1jaGFtb2lzLTQzLmNsZXJrLmFjY291bnRzLmRldiQ

Description

Run pnpm dev

Expected behavior:

The infinite suspense triggered during the server render part of SSR should cause the nearest suspense boundary to display client-side. The client component should not render at all on the client until the suspense is resolved, but it does when we add ClerkProvider to the layout.

Actual behavior:

We see the component being rendered on the client through the console.log statement. (Removing ClerkProvider gets rid of this statement)

This is a dealbreaker for anyone that has SSR + progressive hydration, since the client component starts rendering before the matching server component finishes.

Environment

System:
    OS: macOS 13.4
    CPU: (8) arm64 Apple M2
    Memory: 72.77 MB / 16.00 GB
    Shell: 3.2.57 - /bin/bash
  Binaries:
    Node: 20.12.2 - /usr/local/bin/node
    Yarn: 1.22.11 - /usr/local/bin/yarn
    npm: 10.5.0 - /usr/local/bin/npm
    pnpm: 9.9.0 - /usr/local/bin/pnpm
    bun: 1.1.27
  Browsers:
    Chrome: 130.0.6723.117
    Safari: 16.5
  npmPackages:
    @clerk/nextjs: ^6.3.1 => 6.3.1 
    @types/node: ^20 => 20.17.6 
    @types/react: ^18 => 18.3.12 
    @types/react-dom: ^18 => 18.3.1 
    eslint: ^8 => 8.57.1 
    eslint-config-next: 15.0.3 => 15.0.3 
    next: 15.0.3 => 15.0.3 
    react: 19.0.0-rc-66855b96-20241106 => 19.0.0-rc-66855b96-20241106 
    react-dom: 19.0.0-rc-66855b96-20241106 => 19.0.0-rc-66855b96-20241106 
    typescript: ^5 => 5.6.3

[BRKalow]

Hi there! Could you share more details about what you're trying to accomplish with this pattern? In theory, anything that would cause this component to re-render on the client would trigger the promise again, your linked example exhibits the behavior with next-theme.

[cirex-web]

Any client-component that infinitely suspends on the server should not render on the client, but adding ClerkProvider breaks that functionality.

The reproduction for Clerk is on the clerk branch specifically. Sorry if that wasn't clear
(next-theme had a similar bug, so that's why it's on the main branch)

[BRKalow]

Any client-component that infinitely suspends on the server should not render on the client,

@cirex-web what's the use-case for this pattern? Do you have any docs or articles to share that talks about it further? Thanks!

[cirex-web]

I'm using React Query with SSR, (specifically with the useSuspenseQuery hook,) so if the component renders on client before the same component finishes loading on the server, we get two network requests. (defeating the whole point of SSR'ed requests)

Good overview on React Suspense/Hydration: reactwg/react-18#37